diff --git a/source/docs/help/issues.md b/source/docs/help/issues.md index 2e7b0caf..1acf1a9e 100644 --- a/source/docs/help/issues.md +++ b/source/docs/help/issues.md @@ -4,61 +4,45 @@ title: Issues description: "Got issues?" --- -**[First lets start out by stating that _ALL_ issues should be reported here](https://github.com/hacs/integration/issues)** +This page shows you how to report an issue for HACS. -# What should be in the issue? +# Reporting an issue -When you create an issue in the repository for HACS, you start by selecting a template. +If you're having an issue with a custom element, [report an issue for that repository](/docs/use/repositories/dashboard.md/#reporting-an-issue-with-a-repository). -All templates have a defined structure and it is **expected** that you follow it. +To report an issue with HACS, **[use one of the issue templates](https://github.com/hacs/integration/issues)**. -_Issues that are missing required information can (will) be closed._ -## Flag +- All templates have a defined structure. Follow the structure and provide the requested details. +_Issues missing required information will be closed._ -This should **only** be used, when there is grounds for removing (blacklisting) a repository in HACS. +## What should be in the issue -When you are flagging a repository you need to supply at least these: - -- A good description for why. -- The name of the repository. -- Proof that you have tried to contact the owner of that repository (link to issue) - -_If you are flagging it because you don't like it, have issues with it, or it's not working, you should report that to the repository and not here._ - -## Issues - -You use this when you have issues with HACS. - -[To enable debug logs for HACS (required when adding an issue) have a look here](/docs/use/troubleshooting/logs.md). - -Logs are **more** then _just_ errors, with debug logging it gives the person investigating the issue a full picture of what happened. - - -**What an issue should contain depends on the type, but at least:** +The content of the issue depends on the type of issue. At least, include the following information: - A GOOD description of the issue. + - Check out some real-world examples of [good](#examples-of-good-issues) and [bad](#examples-of-bad-issues) issue descriptions. - Debug logs. + - To enable debug logs for HACS, follow [the steps on enabling debug logs](/docs/use/troubleshooting/logs.md). + - Logs are **more** than _just_ errors; debug logging provides a full picture of what happened. - Steps to reproduce the issue. - If the issue is in the UI, add screenshots. - [Diagnostics](/docs/use/troubleshooting/diagnostics.md) -You can see examples of good/bad issues further down on this page. - !!! warning - _Issues that are missing required information can (will) be closed._ + _Issues that are missing required information will be closed._ !!! tip - oh... and almost forgot... `latest` is **NOT** a version. + oh... and almost forgot... `latest` is **NOT** a version. Provide the actual version number. -# Examples +## Issue examples -This is a collection of good/bad issues. +This section provides a collection of good and some bad (unhelpful) issue descriptions. -## Examples of bad issues +### Examples of bad issues ```text @@ -101,14 +85,29 @@ I checked and it exactly how its supposed to be even replaced the whole hacs folder with a fresh download ``` -## Examples of good issues +### Examples of good issues -_Good issues have too much text to extract it (some also have screenshots) but here is a few links:_ +_Good issues have too much text to extract it (some also have screenshots), but a few are linked below:_ - [https://github.com/hacs/integration/issues/452](https://github.com/hacs/integration/issues/452) - [https://github.com/hacs/integration/issues/470](https://github.com/hacs/integration/issues/470) - [https://github.com/hacs/integration/issues/356](https://github.com/hacs/integration/issues/356) +# Flagging a repository for removal + +This should **only** be used when there are grounds for removing (blacklisting) a repository in HACS. + +_If you don't like a repository, have issues with it, or it's not working, you should report that to the repository owner, not to HACS._ + +When you are flagging a repository, provide at least the following information: + +- A reason why this repository should be removed. + - "It's not working" is not an accepted reason. + - "It's not working and it has not been maintained for an extended period of time" could be a reason. +- The name of the repository. +- Proof that you have tried to contact the owner of that repository. + - Provide a link to the issue you created in their GitHub repository. + # Last words -The more time/words/examples you put in your issue, the faster someone can see/understand what you mean. +The more time/words/examples you put into your issue, the better the chance someone else can understand what your issue is. You are more likely to get help.