diff --git a/basics_dev/reporting-bugs.md b/basics_dev/reporting-bugs.md index 6a00214b..5e06cbd8 100644 --- a/basics_dev/reporting-bugs.md +++ b/basics_dev/reporting-bugs.md @@ -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)