Merge branch 'issue-tracking'

developer/general/doc-guidelines.md

@@ -54,7 +54,7 @@ send it to the appropriate [mailing list](/support/). If you see that something
 in the documentation should be fixed or improved, please
 [contribute](#how-to-contribute) the change yourself. To report an issue with
 the documentation, please follow our standard [issue reporting
-guidelines](/doc/reporting-bugs/). (If you report an issue with the
+guidelines](/doc/issue-tracking/). (If you report an issue with the
 documentation, you will likely be asked to address it, unless there is a clear
 indication in your report that you are not willing or able to do so.)
 
@@ -70,7 +70,7 @@ A few notes before we get started:
   and protect our users.
 * We don't want you to spend time and effort on a contribution that we can't
   accept. If your contribution would take a lot of time, please [file an
-  issue](/doc/reporting-bugs/) for it first so that we can make sure we're on
+  issue](/doc/issue-tracking/) for it first so that we can make sure we're on
   the same page before significant works begins.
 * Alternatively, you may already have written content that doesn't conform to
   these guidelines, but you'd be willing to modify it so that it does. In this

introduction/contributing.md

@@ -18,7 +18,7 @@ ways in which you can help:
 * [Send patches](/doc/source-code/#how-to-send-patches) to fix bugs or
   implement features
 * [Contribute packages](/doc/package-contributions)
-* [Report bugs](/doc/reporting-bugs/)
+* [Report bugs](/doc/issue-tracking/)
 * [Test new releases and updates](/doc/testing/)
 * Submit [HCL reports](/doc/hcl/) for your hardware
 * Record [video tours](/video-tours/)

introduction/faq.md

@@ -311,7 +311,7 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
 2. Our platform supports it, but we've decided not to enable it.
 3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so.
 
-If it seems like a feature that we can and should enable, please [let us know](/doc/reporting-bugs/)!
+If it seems like a feature that we can and should enable, please [let us know](/doc/issue-tracking/)!
 
 ## Users
 

introduction/issue-tracking.md

@@ -1,8 +1,9 @@
 ---
 lang: en
 layout: doc
-permalink: /doc/reporting-bugs/
+permalink: /doc/issue-tracking/
 redirect_from:
+- /doc/reporting-bugs/
 - /en/doc/reporting-bugs/
 - /doc/BugReportingGuide/
 - /wiki/BugReportingGuide/
@@ -12,30 +13,115 @@ redirect_from:
 - /bug-report/
 - /bug-reports/
 ref: 121
-title: Reporting Bugs and Other Issues
+title: Issue Tracking
 ---
 
-All issues pertaining to the Qubes OS Project (including auxiliary
+The Qubes OS Project uses the "GitHub Issues" [issue tracking
-infrastructure such as the [website](/)) are tracked in
+system](https://en.wikipedia.org/wiki/Issue_tracking_system). All issues
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues), our GitHub
+pertaining to the Qubes OS Project (including auxiliary infrastructure such as
-issue tracker. If you're looking for help, please see [Help, Support, Mailing
+the [website](/)) are tracked in
-Lists, and Forum](/support/).
+[qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
 
-## Important ##
+## I would like to report a security vulnerability
 
-- **To disclose a security issue confidentially, please see the
+Please see [Reporting Security Issues in Qubes
-  [Security](/security/) page.**
+OS](/security/#reporting-security-issues-in-qubes-os).
 
-- **In all other cases, please do not email individual developers about
+## I need help, have a question, or want to discuss something
-  issues.**
 
-- **Please note that many issues can be resolved by reading the
+Please see [Help, Support, Mailing Lists, and Forum](/support/).
-  [documentation](/doc/).**
 
-- **If you see something that should be changed in the documentation, [submit a
+## I see something that should be changed in the documentation
-  change](/doc/doc-guidelines/).**
 
-## Search Tips ##
+Please see the [Documentation Guidelines](/doc/doc-guidelines/).
+
+## How to open a new issue
+
+1. Carefully read the [issue tracker guidelines](#issue-tracker-guidelines).
+2. [Search through the existing issues, both open and closed, to see if your
+   issue already exists.](#search-tips)
+3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose).
+4. Select the [type](#type) of issue you want to open.
+5. Enter a descriptive title.
+6. Do not delete the provided issue template. Fill out every applicable
+   section.
+7. Make sure to mention any relevant documentation and other issues you have
+   already seen. We do not know what you have seen unless you tell us. If you
+   do not list it, we will assume you haven't seen it.
+8. If any sections of the issue template are *truly* not applicable, you may
+   remove them, **except for the documentation and related issues sections**.
+9. Submit your issue.
+10. [Follow-up afterward.](#following-up-afterward)
+
+## Labels and milestones
+
+Only Qubes team members have permission to modify
+[labels](https://github.com/QubesOS/qubes-issues/labels) and
+[milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels
+and milestones have descriptions on them that can be viewed either in their
+respective lists or by hovering over them. Let's go over some of the most
+important ones.
+
+### Type
+
+There are three **types**: `T: bug`, `T: enhancement`, and `T: task`.
+
+- `T: bug` --- Type: bug report. A problem or defect resulting in unintended
+  behavior in something that exists.
+- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist
+  **or** improvement of existing functionality.
+- `T: task` --- Type: task. An action item that is neither a bug nor an
+  enhancement.
+
+Every open issue should have **exactly one** type. An open issue should not
+have more than one type, and it should not lack a type entirely. Bug reports
+are for things that already exist. If something doesn't exist yet, but you
+think it should exist, then `T: enhancement`. If something already exists and
+could be improved in some way, `T: enhancement` is appropriate. `T: task` is
+for issues that fall under under neither `T: bug` nor `T: enhancement`.
+
+### Priority
+
+There are several **priority** levels ranging from `P: minor` to `P: blocker`
+(see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full
+list). Every open issue should have **exactly one** priority. An open issue
+should not have more than one priority, and it should not lack a priority
+entirely.
+
+### Component
+
+There are many **component** labels, each beginning with `C:` (see
+[here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the
+full list). Every open issue should have **at least one** component. An open
+issue may have more than one component, but it should not lack a component
+entirely. When no other component applies, use `C: other`.
+
+### Milestones
+
+The issue tracker has several
+[milestones](https://github.com/QubesOS/qubes-issues/milestones). Every issue
+should be assigned to **exactly one** milestone. The issue tracker does not
+allow assigning an issue to more than one milestone. If an issue is already
+assigned to a milestone, assigning it to a different one will *replace* the
+existing milestone assignment. No open issue should lack a milestone
+assignment.
+
+Most milestones correspond to specific Qubes OS releases. A bug report assigned
+to a release milestone indicates an alleged bug *in* that Qubes OS release. A
+task or enhancement assigned to a release milestone indicates that the goal is
+to implement or do that thing *in* or *for* that Qubes OS release.
+
+The `TBD` (To Be Determined) milestone is for enhancements or tasks that will
+be specific to a Qubes OS release but have yet to be assigned to a specific
+release milestone. Bug reports should never be assigned to this milestone,
+because every bug is a problem or defect in something that already exists.
+
+The `Ongoing` milestone is for issues that are independent of the Qubes OS
+release cycle, including (but not limited to) website, documentation, and
+project management issues. These are issues that will never be assigned to a
+specific Qubes OS release milestone.
+
+## Search Tips
 
 [Search both open and closed
 issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue)
@@ -56,14 +142,9 @@ by component
 [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22),
 etc.).
 
-Only Qubes team members can apply labels. Every issue must have exactly one
+## Issue tracker guidelines
-**type** (`T: bug`, `T: enhancement`, or `T: task`), exactly one **priority**
-(e.g., `P: major`), and at least one **component** (e.g., `C: core`). Issues
-may have additional labels, if applicable (e.g., `crypto`, `ux`).
 
-## Issue tracker guidelines ##
+### The issue tracker is not a discussion forum
-
-### The issue tracker is not a discussion forum ###
 
 The issue tracker is a tool to help the developers be more productive and
 efficient in their work. It is not a place for discussion. If you wish to
@@ -83,7 +164,7 @@ we sometimes have to close the issue and open a new one. This is a waste of
 energy for everyone involved, so we ask that everyone help to avoid repeating
 this pattern.
 
-### Do not submit questions ###
+### Do not submit questions
 
 [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place
 to ask questions. This includes, but is not limited to, troubleshooting
@@ -94,7 +175,7 @@ questions. By contrast,
 tracking more general bugs, enhancements, and tasks that affect a broad range
 of Qubes users.
 
-### Use the issue template ###
+### Use the issue template
 
 When you open a new issue, an issue template is provided for you. Please use
 it. Do not delete it. The issue template is carefully designed to elicit
@@ -105,7 +186,7 @@ please do so only sparingly and only if they are *truly* not applicable.)
 It is also important to note the placement and content of the HTML comments in
 the issue template. These help us to have issues with a consistent format.
 
-### Every issue must be about a single, actionable thing ###
+### Every issue must be about a single, actionable thing
 
 If your issue is not actionable, please see [Help, Support, Mailing Lists, and
 Forum](/support/) for the appropriate place to post it. If your issue would be
@@ -123,7 +204,7 @@ discussion that is simply not appropriate for a technical issue tracker (see
 [the issue tracker is not a discussion
 forum](#the-issue-tracker-is-not-a-discussion-forum)).
 
-### New issues should not be duplicates of existing issues ###
+### 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
@@ -139,14 +220,14 @@ 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
 "Subscribe" button at the side or bottom of the comments.
 
-### Every issue must be of a single type ###
+### Every issue must be of a single type
 
 Every issue must be exactly one of the following types: a bug report (`bug`), a
 feature or improvement 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 ###
+### 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
@@ -161,7 +242,7 @@ the [updates-status](https://github.com/QubesOS/updates-status/issues)
 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 ###
+### 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
@@ -173,7 +254,7 @@ 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 ##
+## Following up afterward
 
 If the Qubes developers make a code change that resolves your issue, then your
 GitHub issue will typically be closed from the relevant patch message. After
@@ -194,7 +275,7 @@ we're closing the issue with one of these specific resolutions. If the issue is
 closed without one of these specific resolutions, then it means, by default,
 that your reported bug was fixed or your requested enhancement was implemented.
 
-## See also ##
+## See also
 
 - [Help, Support, Mailing Lists, and Forum](/support/)
 - [Testing New Releases and Updates](/doc/testing/)

introduction/support.md

@@ -23,10 +23,10 @@ Before asking for help, please check the [troubleshooting](/doc/#troubleshooting
 Your question may already be answered there.
 
 If you're looking for known issues or would like to file a bug report, please
-see the [issue tracker](/doc/reporting-bugs/). These issues are constantly being updated and may
+see the [issue tracker](/doc/issue-tracking/). These issues are constantly being updated and may
 contain workarounds for problems that you're experiencing, so it's worth
-[searching the issue tracker](/doc/reporting-bugs/#search-tips) as a first step. However, please note that
+[searching the issue tracker](/doc/issue-tracking/#search-tips) as a first step. However, please note that
-[the issue tracker is not a discussion forum](/doc/reporting-bugs/#the-issue-tracker-is-not-a-discussion-forum).
+[the issue tracker is not a discussion forum](/doc/issue-tracking/#the-issue-tracker-is-not-a-discussion-forum).
 
 ## Staying safe
 
@@ -141,8 +141,8 @@ Conduct](/code-of-conduct/) for more information.
 
 The mailing lists and [forum](#forum) are good places to ask questions and discuss
 things. However, if you're submitting a more formal report, we'd prefer that
-you submit it to our [issue tracker](/doc/reporting-bugs/) so that it doesn't get overlooked.
+you submit it to our [issue tracker](/doc/issue-tracking/) so that it doesn't get overlooked.
-(However, please remember that [the issue tracker is not a discussion forum](/doc/reporting-bugs/#the-issue-tracker-is-not-a-discussion-forum).)
+(However, please remember that [the issue tracker is not a discussion forum](/doc/issue-tracking/#the-issue-tracker-is-not-a-discussion-forum).)
 Likewise, if you see that something in the documentation should be changed,
 don't simply point it out in a discussion venue. Instead, [submit the
 change](/doc/doc-guidelines/).

user/downloading-installing-upgrading/testing.md

@@ -24,7 +24,7 @@ How to test upcoming Qubes OS releases:
 * (No support) Experiment with devel alpha ISOs found from time to time at
   [Qubes OpenQA](https://openqa.qubes-os.org/).
 
-Please make sure to [report any bugs you encounter](/doc/reporting-bugs/).
+Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
 
 See [Version Scheme](/doc/version-scheme/) for details about release versions
 and schedules. See [Release Checklist](/doc/releases/todo/) for details about
@@ -80,6 +80,6 @@ testing repository. Even a simple <span class="fa fa-thumbs-up" title="Thumbs
 Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on
 the package's associated issue would help us to decide whether the package is
 ready to be migrated to a stable repository. If you [report a
-bug](/doc/reporting-bugs/) in a package that is in a testing repository, please
+bug](/doc/issue-tracking/) in a package that is in a testing repository, please
 reference the appropriate issue in
 [updates-status](https://github.com/QubesOS/updates-status/issues).

user/security-in-qubes/u2f-proxy.md

@@ -131,5 +131,5 @@ The large number of possible combinations of template (Fedora 27, 28; Debian 8,
 In some cases, you may be the first person to try a particular combination.
 Consequently (and as with any new feature), users will inevitably encounter bugs.
 We ask for your patience and understanding in this regard.
-As always, please [report any bugs you encounter](/doc/reporting-bugs/).
+As always, please [report any bugs you encounter](/doc/issue-tracking/).