Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update "Issue Tracking"

Browse Source 
- Improve section organization
- Improve new issue instructions
- Add section on "projects"
- Convert final section into "How issues get closed"
- Add section on backports (closes QubesOS/qubes-issues#6655)
This commit is contained in:
Andrew David Wong 2021-06-21 01:43:38 -07:00
parent dd24aebf29
commit 0c3c2aa82d
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 92 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
introduction/issue-tracking.md
View File

@ -22,38 +22,53 @@ pertaining to the Qubes OS Project (including auxiliary infrastructure such as
the [website](/)) are tracked in
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
## I would like to report a security vulnerability
## How to open a new issue
First, let's make sure the issue tracker is the right place.
### I would like to report a security vulnerability
Please see [Reporting Security Issues in Qubes
OS](/security/#reporting-security-issues-in-qubes-os).
## I need help, have a question, or want to discuss something
### I need help, have a question, or want to discuss something
Please see [Help, Support, Mailing Lists, and Forum](/support/).
## I see something that should be changed in the documentation
### I see something that should be changed in the documentation
Please see the [Documentation Guidelines](/doc/doc-guidelines/).
We encourage you to submit the change yourself! Please see the [Documentation
Guidelines](/doc/doc-guidelines/) for instructions on how to do so. If it's
something you can't do yourself, please proceed to the next section.
## How to open a new issue
### I still want to open an 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)
1. Carefully read our issue tracking [guidelines](#guidelines). If your issue
would violate any of the guidelines, **stop**. Please do not submit it.
2. [Search through the existing issues](#search-tips), both open and closed, to
see if your issue already exists. If it does, **stop**. [Do not open a
duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues)
Instead, comment on the existing issue.
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.
7. Make sure to mention any relevant documentation and other issues you've
already seen. We don't know what you've seen unless you tell us. If you
don't list it, we'll 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)
10. Respond to any questions the official team asks. For example, you may be
asked to provide specific logs or other additional information.
## Labels and milestones
## Labels, Milestones, and Projects
Labels, milestones, and projects are features of GitHub's issue tracking system
that we use to keep `qubes-issues` organized.
### Labels
Only Qubes team members have permission to modify
[labels](https://github.com/QubesOS/qubes-issues/labels) and
@ -62,7 +77,7 @@ 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
#### Type
There are three **types**: `T: bug`, `T: enhancement`, and `T: task`.
@ -80,7 +95,7 @@ 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
#### 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
@ -88,7 +103,7 @@ 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
#### 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
@ -121,6 +136,14 @@ 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.
### Projects
The issue tracker has several
[projects](https://github.com/QubesOS/qubes-issues/projects). A project is a
way to create a group of multiple related issues. This is the preferred method
of grouping issues, whereas trying to use normal issues as "meta-issues" or
"epics" is discouraged.
## Search Tips
[Search both open and closed
@ -142,7 +165,9 @@ by component
[Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22),
etc.).
## Issue tracker guidelines
You can also try searching by [milestone](https://github.com/QubesOS/qubes-issues/milestones) and by [project](https://github.com/QubesOS/qubes-issues/projects).
## Guidelines
### The issue tracker is not a discussion forum
@ -254,26 +279,63 @@ 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
## How issues get closed
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
that, the package containing the fix will move to the appropriate
[testing](/doc/testing/) repository, then to the appropriate stable repository.
If you so choose, you can test the fix while it's in the
If the Qubes developers make a code change that resolves an issue, then the
issue will typically be [closed from the relevant commit or merged pull request
(PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue).
### Bug reports
In the case of bugs, the package containing the change will move to the
appropriate [testing](/doc/testing/) repository, then to the appropriate stable
repository. If you so choose, you can test the fix while it's in the
[testing](/doc/testing/) repository, or you can wait for it to land in the
stable repository. If, after testing the fix, you find that it does not really
fix your bug, please leave a comment on your issue explaining the situation.
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.
fix the reported bug, please leave a comment on the issue explaining the
situation. When you do, we will receive a notification and respond on the issue
or reopen it (or both). Please **do not** create a duplicate issue or attempt
to contact the developers individually about a problem.
In other cases, your issue may be closed with a specific resolution, such as
`R: invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a
### Resolution
In other cases, an issue may be closed with a specific resolution, such as `R:
invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a
description that explains the label. We'll also leave a comment explaining why
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.
that the reported bug was fixed or the requested enhancement was implemented.
### Backports
Issues in GitHub can only be open or closed, but, when it comes to bugs that
affect multiple versions of Qubes OS, there are several possible states:
1. Not fixed yet
2. Fix developed but not yet committed (PR open)
3. Fix committed (PR merged), but update not yet pushed to any repo
4. Update pushed to testing repo for the most recent development version
5. Update pushed to stable repo for the most recent development version
6. Update backported to stable version(s) and pushed to the testing repo
7. Update pushed to stable repo of stable version(s)
We close issues at step 3. Then, as updates are released, the issue
automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and
`stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to
select issues waiting for step 6 (see [issues by
release](https://github.com/QubesOS/qubes-issues#issues-by-release)).
Therefore, if you see that an issue is closed, but the fix is not yet available
to you, be aware that it may be at an intermediate stage of this process
between issue closure and the update being available in whichever repos you
have enabled in whichever version of Qubes you're using.
In order to assist with this, we have a label called [backport
pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending),
which means, "The fix has been released for the testing release but is pending
backport to the stable release." Our infrastructure will attempt to apply this
label automatically, when appropriate, but it is not perfect, and the
developers may be need to adjust it manually.
## See also