Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-03-06 13:46:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Reorganize and update issue reporting page

Browse Source
This commit is contained in:
Andrew David Wong 2018-08-16 17:09:25 -05:00
parent e7ab6f4fe7
commit 7f0b6da48e
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 68 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
basics_user/reporting-bugs.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Reporting Bugs
title: Reporting bugs and other issues
permalink: /doc/reporting-bugs/
redirect_from:
- /en/doc/reporting-bugs/
@ -13,65 +13,67 @@ redirect_from:
- /bug-reports/
---
Reporting Bugs
==============
One of the most important ways in which you can [contribute to the Qubes OS Project] is by reporting any bugs you have found.
Important
---------
- **To disclose a security issue confidentially, please see the [Security] page.**
- **In all other cases, please do not email individual developers about bugs.**
- **Please note that many issues can be resolved by reading the [documentation].**
`qubes-issues` guidelines
-------------------------
# Reporting bugs and other issues #
All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website]) are tracked in [qubes-issues], our GitHub issue tracker.
- **Do not submit questions.**
[qubes-issues] is not the place to ask questions.
This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes.
These questions should instead be asked in [qubes-users].
Instead, [qubes-issues] is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
## Important ##
- **Every issue must be about a single, actionable thing.**
If your issue is not actionable, please send it to the appropriate [mailing list][mailing list guidelines] instead.
If your issue would be about more than one thing, file them as separate issues instead.
- **To disclose a security issue confidentially, please see the [Security] page.**
- **In all other cases, please do not email individual developers about issues.**
- **Please note that many issues can be resolved by reading the [documentation].**
- **If you see something that should be changed in the documentation, [submit a change][Documentation Guidelines].**
- **New issues should not be duplicates of existing issues.**
Before you submit an issue, check to see whether it has already been reported.
Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box.
If you find an issue that seems to be similar to yours, read through it.
If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed.
The Qubes team will see your comment and reopen the issue, if appropriate.
For example, you can leave a comment with additional information to help the maintainer debug it.
Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue.
If you don't have anything to add but still want to receive email updates, you can click the "watch" button at the bottom of the comments.
## Issue tracker guidelines ##
- **Every issue must be of a single type.**
Every issue must be exactly one of the following types: a bug report (`bug`), a feature request (`enhancement`), or a task (`task`).
Do not file multi-typed issues.
Instead, file multiple issues of distinct types.
The Qubes team will classify your issue according to its type.
### Do not submit questions ###
- **New issues should include all relevant information.**
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages.
If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`.
If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository.
Project maintainers really appreciate thorough explanations.
It usually helps them address the problem more quickly, so everyone wins!
[qubes-issues] is not the place to ask questions.
This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes.
These questions should instead be asked in [qubes-users].
By contrast, [qubes-issues] is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
- **There are no guarantees that your issue will be addressed.**
Keep in mind that `qubes-issues` is an issue tracker, not a support system.
Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration.
It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it.
Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all.
At the time of this writing, there are well over one thousand open issues in `qubes-issues`.
The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
### Every issue must be about a single, actionable thing ###
If your issue is not actionable, please send it to the appropriate [mailing list][Help, Support, and Mailing Lists] instead.
If your issue would be about more than one thing, file them as separate issues instead.
### New issues should not be duplicates of existing issues ###
Before you submit an issue, check to see whether it has already been reported.
Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box.
If you find an issue that seems to be similar to yours, read through it.
If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed.
The Qubes team will see your comment and reopen the issue, if appropriate.
For example, you can leave a comment with additional information to help the maintainer debug it.
Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue.
If you don't have anything to add but still want to receive email updates, you can click the "watch" button at the bottom of the comments.
### Every issue must be of a single type ###
Every issue must be exactly one of the following types: a bug report (`bug`), a feature request (`enhancement`), or a task (`task`).
Do not file multi-typed issues.
Instead, file multiple issues of distinct types.
The Qubes team will classify your issue according to its type.
### New issues should include all relevant information ###
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0]).
If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`.
If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository.
Project maintainers really appreciate thorough explanations.
It usually helps them address the problem more quickly, so everyone wins!
### There are no guarantees that your issue will be addressed ###
Keep in mind that `qubes-issues` is an issue tracker, not a support system.
Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration.
It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it.
Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all.
At the time of this writing, there are well over one thousand open issues in `qubes-issues`.
The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
## Following up afterward ##
If your issue is addressed, your GitHub issue may be closed.
After that, the package containing the fix will move to the appropriate [testing] repository, then to the appropriate stable repository.
@ -80,43 +82,28 @@ If, after testing the fix, you find that it does not really fix your bug, please
When you do, we will receive a notification and respond on your issue or reopen it (or both).
Please **do not** create a duplicate issue or attempt to contact the developers individually about your problem.
## See also ##
Mailing list guidelines
-----------------------
Please see the [Mailing Lists][support] page.
- [Help, Support, and Mailing Lists]
- [Testing New Releases and Updates]
- [How to Contribute]
- [Contributing Code]
- [Package Contributions]
- [Documentation Guidelines]
How to copy information out of dom0
-----------------------------------
Copying information out of dom0 can be useful when reporting bugs.
See [Copying from (and to) dom0] for more information.
Testing new releases and updates
--------------------------------
Please see [Testing New Releases and Updates][testing].
Improving the code
------------------
Please see our guidelines on [how to contribute code].
[contribute to the Qubes OS Project]: /doc/contributing/
[Security]: /security/
[documentation]: /doc/
[website]: /
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[mailing list guidelines]: #mailing-list-guidelines
[support]: /support/
[Help, Support, and Mailing Lists]: /support/
[qubes-users]: /support/#qubes-users
[qubes-devel]: /support/#qubes-devel
[testing]: /doc/testing/
[updates-status]: https://github.com/QubesOS/updates-status/issues
[Copying from (and to) dom0]: /doc/copy-from-dom0/
[how to contribute code]: /doc/contributing/#contributing-code
[how to copy information out of dom0]: /doc/copy-from-dom0/
[Testing New Releases and Updates]: /doc/testing/
[How to Contribute]: /doc/contributing/
[Contributing Code]: /doc/contributing/#contributing-code
[Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/