architecture
architecture copied to clipboard
home-assistant
List of known _major_ issues
Context
As mentioned in https://github.com/home-assistant/home-assistant.io/pull/10102 we've got cases where there's a known issue, such as stream and shell_command causing HA to crash.
While things like this can be found in the issues list, if you know what to search for, it's far from easy, and people quite reasonably expect that things like this aren't so hard to find.
Proposal
The creation of a known issues page, or an easy way to find known issues for an integration without having to know Git-fu.
This may require that issues are tagged in a way so that people can separate out confirmed from the still unknown.
Consequences
People find it easier to find known issues.
Here is a case in point. We know that the Google Home component is broken until/unless Google revert their changes.
We don't want to warn people of that though. Instead choosing to let them set it up, fail, and get frustrated 🤷♂
Would be nice if this ADR actually listed a concrete solution to work with. Multiple were provided in home-assistant/home-assistant.io#10102.
Yet you've not responded on any of them, nor did you provide any concrete plans on resolving this. Well, you do, using manual methods, which I strongly disagree with from a maintenance perspective.
I agree manual is far from optimal.
However, right now we're deliberately letting people fall over known problems.
So, I don't really care whether we go with:
- A known issues page we manually update
- Tagging GitHub issues and having the page built automatically (Balloob's suggestion)
- Tagging GitHub issues and having warnings automatically highlight them (Sean's suggestion)
- Something else
We need something better than the current approach. Sure, it keeps the docs "cleaner", but it's causing frustration to end users.
The only concrete plan I can provide is (1) - because I'm not a developer, I don't have the skills to do Git-fu to make (2) or (3) work. Not that I see any point in doing anything towards that, because it's clear that you'll just close or revert any such PR ;)
I dont think us as mods would mind a page that we could point to for known (major) issue that we could easily update. We see the problems first hand in discord. I like automation but that should not get in the way of keeping someone from trying for hours over a known issue such as the dns issue in hassio.
I can adjust our documentation to include a link in the sidebar of each integration page to a filtered list of issue in about 15 minutes of work.
Example for googlehome:
🐞 Check our issue tracker for reported issues on this integration
Well thats sweet but does it tell the user that its not working and wait for a fix?
Depends if somebody wrote it down... just like when you would have put it anywhere else...
It is now written down, though of course I don't have the ability to add labels, so it'll need somebody else to flag this specific issue.
Thanks though, this is a good first step.
@frenck what i meant is i read the issues and did not see dont use this it is broken right now I am thinking of the poor guy that dont quite know how to read the issues
? That makes no sense at all. The issues for it already existed, you've just created a low-quality general issue that is a duplicate.
@DubhAd https://github.com/home-assistant/home-assistant/issues/24815, and yes, it is listed when you look at the link I gave above.
do you ever look at things from a non programmer respective and like a user would ..... You are very smart but they guy trying to use the software may not understand and we are simply wanting a way to convey to them.
A first step towards using issues as a reference for major issues would be a triage process, as mentioned in https://github.com/home-assistant/home-assistant.io/pull/10102#issuecomment-520630727. However, I think that tagging with user impact is different from an issue just being confirmed. So I would add another tag (or issue type, but that tracker could instantly get polluted with low quality issues).
With labels for integration, triage status, and user impact, it becomes trivial to get the relevant information from the Github API. Very feasible to integrate in documentation on build. However, an issue does not necessarily describe user impact in meaningful terms. The issue names in the tracker are of low quality. A high quality problem description would describe the root cause and not be a description of user impact.
True.
If the issue title would be edited to become a partial user story when it is tagged with user impact, that would be enough.
On Sat, 17 Aug 2019, 20:19 Franck Nijhof, [email protected] wrote:
@ties https://github.com/ties That would be just a matter of taking care of proper issue naming.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/home-assistant/architecture/issues/272?email_source=notifications&email_token=AABQTET7265BKOCWYR3AE5TQFA6J3A5CNFSM4ILJ747KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4QQ3II#issuecomment-522259873, or mute the thread https://github.com/notifications/unsubscribe-auth/AABQTEVJX6OKGIRNHZKKYG3QFA6J3ANCNFSM4ILJ747A .
I don't believe in using GitHub issues. They are too limited. Especially if we would want such a system to be hooked into Home Assistant. Because if we can organize the info, why wait for the user to look at a page, we could alert them.
I've wipped up a quick proof of concept for a Home Assistant Alerts where we can keep track of such things.
http://temp-demo-alerts.s3-website-us-east-1.amazonaws.com/
It would work with markdown files that can have metadata like our forum has. Example
---
title: "Stream integration incompatible with X"
created: 2019-08-18 21:11:03
updated: 2019-08-18 23:11:03
packages:
- uvloop >0.1
integrations:
- stream >0.32 <0.60
- ffmpeg >0.54
github_issue: https://github.com/home-assistant/home-assistant/issues/22999
---
_This is demo content._
There is a known issue with `uvloop` and the stream integration.
Integration version numbers would be now the same as HA version numbers as long as we don't have standalone releases.
More info in the GitHub repo https://github.com/home-assistant/alerts.home-assistant.io/
I don't believe in using GitHub issues. They are too limited. Especially if we would want such a system to be hooked into Home Assistant. Because if we can organize the info, why wait for the user to look at a page, we could alert them.
I like the structured information more but did not want to introduced a more complex approach with structured information before others agreed that there was an issue. This could integrated really well with the updater and/or notifications.
Two notes:
- github_issue likely needs to be a list
- I think you have python packages that can cause issues, dependencies that cause issues (e.g. ffmpeg), and integrations. I think you need to split these up.
An integration would depend on other integrations, python packages, and system dependencies to be installed. This maps to dependencies, requirements in manifest.json, system dependencies are implicit.
@DubhAd do you think the new alerts website will be a sufficient fix for this issue?
@DubhAd do you think the new alerts website will be a sufficient fix for this issue?
With two caveats, yes.
- We really need a way of dynamically updating the component page with links to relevant alerts - push the information in the face of the users. This will avoid folks trying to set something up and getting frustrated.
- It would be good to add a persistent notification in HA about known issues with the components people are using, or maybe in the server control section alongside the config check?
No implementations yet but I wrote them down.
- https://github.com/home-assistant/alerts.home-assistant.io/issues/7
- https://github.com/home-assistant/alerts.home-assistant.io/issues/8