Surface known critical issues on integration documentation pages

[fdmarcin]

Problem statement

When a documented integration has a known, reproducible bug that breaks core functionality (for example, the Xiaomi Home integration's authentication flow not handling a CAPTCHA code sent by Xiaomi's cloud during initial setup), users currently have no reliable way to learn this before attempting setup themselves and failing.

The only existing path to this information is the "View pending feedback" link below each integration's documentation page, which surfaces related GitHub issues.

In practice this is hard to discover: a user has to know the feature exists, scroll past the page content, and then read through a list of issues to find the relevant one. New and non-technical users - the audience OHF's accessibility goals are most focused on - are the least likely to know this path exists or to feel comfortable parsing a GitHub issue tracker to determine whether what they're seeing is a known problem.

This erodes trust in the documentation. If a user follows the documented steps exactly and fails due to an undocumented, known bug, they reasonably conclude the documentation is wrong, rather than understanding the actual situation: it's correct, but incomplete in a way that materially affects them.

The harm isn't limited to setup failure. Several users report buying specific hardware because Home Assistant's documentation listed an integration for it, only to discover after purchase that the integration doesn't work. By the time they find out, the purchase decision has already been made and can't be undone by a documentation fix.

This opportunity is about closing that gap for users, not about deciding whether or how fast bugs get fixed. The bug itself should still be fixed through the normal process; this is about what, if anything, users are told in the time before a fix lands - which, in the Xiaomi Home case, has already been over a year.

Community signals

For the example problem (Xiaomi Home), users expressing frustration at not knowing about the bug before a purchase or feeling unsure whether it's going to be fixed:

• The open and closed issues, totalling ~180 upvotes.

  Why is it the preferred solution to close/ignore this issue, instead of at least but removing the non-working integration out of the standard HA interface/integration? This is super frustrating and surely won't help with getting people excited to use HA.

  Instead of closing this issue one of two things should happen:
  a) The bug will be fixed and the standard integration should use the working login from one of the other Xiaomi integrations that are advertised here.
  b) the standard integration should be replaced with one of the working alternatives

  or c) removed from 'basic' HA. When someone wants to add a xiaomi product, they should be guided to a readme of an up-to-date explanation or nothing.

  there is nothing that says flawed product stay away as strongly as a broken feature within the first 5 minutes of using...

  it being an integration officialy "endorsed" by Home Assistant - both on website and in the solution itself - including being shown to complete newbies while new users can't use it seems counterintuitive. At least it should not be shown as an integration you can add if you... well... cannot add it and developers confirmed they won't release a fix.

  I hope that the situation with this integration will not turn out to be the same as with Tuya (which the developers abandoned and the status updates in it have not been working for almost a year).

  New vacuum picked for this integration so sad

  Same issue here. I’m a new HA user, I decided to bought a HA green 3 weeks ago after reviewing all the available integrations, especially this one. Please help us to help you!

  To be honest, I ordered the Dreame X40 specifically because of its Xiaomi integration with Home Assistant

  everyone said take home assistant its super easy and all works well. I think I should have just used homebridge and stayed with apple homekit... I am sitting here and wasting hours of my life. Please help. Thanks already for help.

  HA comes with a lot of tinkering especially if you deal with unofficial third-party integrations [Ed: this isn't a third party integration]

• Reddit thread

  Same issue here and I am new to Home Assistant so I am very hesitant to do manual configuration.

• Forum threads: one, two

  This integration is NOT working and should be removed from Home Assistant. Currently it is wasting everybody’s time and giving false hopes / promises of making Xiaomi products work with HA. I purchased the Xiaomi Tower Fan 2 with the expectation that I would be able to control it via HA because of the available integration. Big mistake.

Scope & Boundaries

In scope

• Evaluating whether the current "View pending feedback" mechanism is visible enough for critical, setup-blocking issues, and if not, what would make it more visible
• Considering options ranging from minimal (improving visibility/placement of the existing feedback link) to more involved (a standardized, link-only notice for critical issues), without committing to either at this stage
• Defining what qualifies as a "critical" issue for the purposes of this opportunity (for example, blocks initial setup or core functionality entirely vs. a minor bug)
• Defining when such a notice or improved visibility is added and removed (tied to the lifecycle of the linked GitHub issue - added when filed/confirmed, removed when closed)

Not in scope

• Changing how, or how quickly, bugs are triaged or fixed.
• Writing bug descriptions directly into documentation pages (this would conflict with the docs-known-limitations quality scale rule, which explicitly asks contributors to refrain from describing bugs in docs to avoid duplicating the GitHub issue tracker).
• Integration deprecation or removal policy (a separate, heavier mechanism already used for integrations that are durably unfixable, for example, due to upstream API changes).

Foreseen solution

This opportunity does not assume a specific fix. It proposes investigating two non-exclusive directions and deciding which (or both) to pursue:

1. Raise the visibility of the existing "View pending feedback" feature. This requires no new mechanism and stays fully consistent with how the project already separates documentation from the issue tracker. The current placement (below the page, requiring a scroll and a click) may be too easy to miss for a user who doesn't already know it's there.
2. Add a standardized, link-only notice for critical issues, surfaced more prominently on the page (for example, near the top), that points to the relevant GitHub issue without describing the bug in prose. This stays within the spirit of docs-known-limitations - it's a pointer, not a duplicate description - but makes the existence of a known, severe problem unmissable rather than discoverable only by users who go looking.

A consideration for either direction: pointing less technical users directly at a GitHub issue tracker may not be the friendliest experience for OHF's target audience of less technical users. If that's a concern, an alternative is a plain-language notice with the GitHub issue link present but secondary, rather than the primary call to action, for example:

"Setting up this integration currently doesn't work for <reason>. Fixed when <status>."

In both directions, the notice or improved link should appear and disappear automatically (or with minimal manual upkeep) tied to the state of the linked issue, so it doesn't become stale content that someone has to remember to remove.

Risks & open questions

• This opportunity does not address why a setup-blocking bug like the Xiaomi Home CAPTCHA issue can remain unfixed for months. Surfacing the bug to users more clearly does not reduce the importance of fixing it; both should be pursued, and increased visibility should not be treated as a substitute for prioritization.
• Considered and rejected for this opportunity: removing or delisting integrations with critical unfixed bugs. Several users have asked for this directly. It's excluded here because deprecation/removal is a separate, heavier mechanism with its own criteria (see Scope & Boundaries), not because the request isn't valid; it may warrant its own opportunity.

Risks

• Risk of conflicting with docs-known-limitations if not scoped carefully - any solution here must remain a link to the issue tracker, not a description of the bug, to stay consistent with the existing quality scale rule and its stated rationale (avoiding duplicate, divergent information).
• Risk that improved visibility becomes a comfortable long-term substitute for fixing things, rather than a short-term bridge. Some users already compare this case to Tuya, where, according to one user, the integration was abandoned by developers and status updates had not worked for almost a year. A notice mechanism should not make that kind of multi-year neglect more tolerable.

Open questions

• What threshold defines "critical" enough to warrant added visibility? Needs alignment to avoid this becoming noisy across many integrations with minor open issues.
• Open question: if a notice is shown, should it link directly to a GitHub issue, or to a friendlier intermediate page, given the goal of being approachable for less technical users?
• Who is responsible for adding/removing a notice, and is this enforceable without manual upkeep (for example, driven by an issue label or status, rather than a person remembering to update the page)?

Appetite

Small, roughly half a cycle, to investigate both directions and decide which to pursue.

Implementation, if approved separately, would likely range from:

• small (visibility improvements only)
• to medium (a new conditional notice mechanism, requiring frontend template changes)

Execution issues

No response

Decision log

Date	Decision	Outcome