mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-12-28 08:49:42 -05:00
Rewrite Reporting Bugs page
* Organize sections logically according to each step in the bug reporting process * Explain how bugs can be reported in different venues * Explain how to report bugs in qubes-issues (will replace CONTRIBUTING.MD) * Link to Contributing page * Generally improve wording and formatting
This commit is contained in:
Andrew David Wong
parent
c9b06e8b42
commit
5245e53f6b
@ -13,59 +13,63 @@ redirect_from:
|
||||
- /bug-reports/
|
||||
---
|
||||
|
||||
Bug Reporting Guide
|
||||
===================
|
||||
Reporting Bugs
|
||||
==============
|
||||
|
||||
One of the most important contribution tasks is reporting the bugs you have
|
||||
found. Please note that there is a separate process for [reporting security
|
||||
issues](/security/).
|
||||
One of the most important ways in which you can [contribute to the Qubes OS
|
||||
Project] is by reporting any bugs you have found. Please note that there is a
|
||||
separate process for [reporting security issues](/security/).
|
||||
|
||||
Asking a Question
|
||||
-----------------
|
||||
|
||||
Before you ask, do some searching and reading. Check [the
|
||||
docs](https://www.qubes-os.org/doc/), Google, GitHub, and StackOverflow. If
|
||||
your question is something that has been answered many times before, the
|
||||
project maintainers might be tired of repeating themselves.
|
||||
Before you submit a report
|
||||
--------------------------
|
||||
|
||||
Whenever possible, ask your question on the [mailing lists](/mailing-lists/).
|
||||
This allows anyone to answer and makes the answer available for the next person
|
||||
with the same question.
|
||||
Before you submit a bug report, please take a moment to check whether your issue
|
||||
has already been reported and to determine which venue is most approriate for
|
||||
it.
|
||||
|
||||
Submitting a Bug Report (or "Issue")
|
||||
------------------------------------
|
||||
* Read the [documentation] to see whether what you've found is really a bug.
|
||||
|
||||
On GitHub, "Bug Reports" are called "Issues."
|
||||
* Search through the existing [Qubes issues] by typing your key words in the
|
||||
**Filters** box. Make sure to check both currently open issues, as well as
|
||||
issues that are already closed. If you find an issue that seems to be similar
|
||||
to yours, read through it. If this issue is the same as yours, you can
|
||||
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.
|
||||
|
||||
Issues can be submitted to the Qubes project located at
|
||||
[https://github.com/QubesOS/qubes-issues](https://github.com/QubesOS/qubes-issues).
|
||||
* Search through our [mailing list] archives by visiting the Google Groups web
|
||||
interfaces for both [qubes-users] and [qubes-devel].
|
||||
|
||||
### Has This Been Asked Before?
|
||||
|
||||
Before you submit a bug report, you should search existing issues. Be sure
|
||||
to check both currently open issues, as well as issues that are already
|
||||
closed. If you find an issue that seems to be similar to yours, read
|
||||
through it.
|
||||
Where to submit your report
|
||||
---------------------------
|
||||
|
||||
If this issue is the same as yours, you can 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.
|
||||
Our [GitHub issues][qubes-issues] tracker is not intended for personal,
|
||||
localized troubleshooting questions, such as problems that affect only a
|
||||
specific laptop model. Those questions are more likely to be answered in
|
||||
[qubes-users], which receives much more traffic. Instead, GitHub issues are
|
||||
meant to track more general bugs and enhancements that affect a broad range of
|
||||
Qubes users.
|
||||
|
||||
### Nope, Hasn't Been Asked Before
|
||||
|
||||
If you can't find anything in the existing issues, don't be shy about
|
||||
filing a new one.
|
||||
How to submit a report on the mailing lists
|
||||
-------------------------------------------
|
||||
|
||||
You should be sure to include the version the project, as well as versions
|
||||
of related software. For example, be sure to include the Qubes release
|
||||
version (R2, R3) and specific version numbers of package causing problems
|
||||
(if known).
|
||||
If your issue is related to hardware, provide as many details as possible
|
||||
about the hardware, which could include using commandline tools such as
|
||||
`lspci`.
|
||||
Please see the [mailing list guidelines][mailing list].
|
||||
|
||||
|
||||
How to submit a report on GitHub
|
||||
--------------------------------
|
||||
|
||||
We track all bugs in the [qubes-issues] tracker on GitHub.
|
||||
|
||||
When you file a new issue, you should be sure to include the version of Qubes
|
||||
your'e 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`.
|
||||
|
||||
Project maintainers really appreciate thorough explanations. It usually
|
||||
helps them address the problem more quickly, so everyone wins!
|
||||
@ -73,15 +77,14 @@ helps them address the problem more quickly, so everyone wins!
|
||||
Improving the Code
|
||||
------------------
|
||||
|
||||
The best way is to "Fork" the repo on GitHub. This will create a copy of
|
||||
the repo on your GitHub account.
|
||||
Please see our guidelines on [how to contribute code].
|
||||
|
||||
Before you set out to improve the code, you should have a focused idea in
|
||||
mind of what you want to do.
|
||||
|
||||
Each commit should do one thing, and each PR should be one specific
|
||||
improvement. Each PR needs to be signed.
|
||||
[contribute to the Qubes OS Project]: /doc/contributing/
|
||||
[documentation]: /doc/
|
||||
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
|
||||
[mailing lists]: https://www.qubes-os.org/mailing-lists/
|
||||
[qubes-users]: https://groups.google.com/group/qubes-users
|
||||
[qubes-devel]: https://groups.google.com/group/qubes-devel
|
||||
[how to contribute code]: /doc/contributing/#contributing-code
|
||||
|
||||
* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/ContributingHowto/)
|
||||
* [Developer Documentation](https://www.qubes-os.org/doc/)
|
||||
* [Package Release Workflow](https://github.com/QubesOS/qubes-builder/blob/master/doc/ReleaseManagerWorkflow.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user