60a894bded
- Rename to "Issue Tracking" (file rename in separate commit to preserve history) - Break the "Important" section up into multiple shorter sections in an attempt to discourage people from skipping over it - Add "How to open a new issue" section - Add "Labels and milestones" section - Update heading syntax
14 KiB
| lang | layout | permalink | redirect_from | ref | title | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| en | doc | /doc/issue-tracking/ |
|
121 | Issue Tracking |
The Qubes OS Project uses the "GitHub Issues" issue tracking system. All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the website) are tracked in qubes-issues.
I would like to report a security vulnerability
Please see Reporting Security Issues in Qubes OS.
I need help, have a question, or want to discuss something
Please see Help, Support, Mailing Lists, and Forum.
I see something that should be changed in the documentation
Please see the Documentation Guidelines.
How to open a new issue
- Carefully read the issue tracker guidelines.
- Search through the existing issues, both open and closed, to see if your issue already exists.
- Go here.
- Select the type of issue you want to open.
- Enter a descriptive title.
- Do not delete the provided issue template. Fill out every applicable section.
- 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.
- If any sections of the issue template are truly not applicable, you may remove them, except for the documentation and related issues sections.
- Submit your issue.
- Follow-up afterward.
Labels and milestones
Only Qubes team members have permission to modify labels and 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 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 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. 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. For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view all bug reports, both open and closed, with the most recently updated sorted to the top.
Search using labels. For example, you can search issues by priority (blocker, critical, major, etc.) and by component (core, manager/widget, Xen, etc.).
Issue tracker guidelines
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 discuss something in the issue tracker, please do so on the forum or mailing lists (see Help, Support, Mailing Lists, and Forum). You can simply link to the relevant issue in your discussion post.
This guideline is important for keeping issues focused on actionable information, which helps the developers to stay focused on their work. When developers come back to an issue to work on it, we do not want them to have to sift through a large number of unnecessary comments before they can get started. In many cases, an issue that gets "too big" essentially becomes more trouble than it's worth, and no developer will touch it (also see every issue must be about a single, actionable thing). In these cases, 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
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. Instead, see Help, Support, Mailing Lists, and Forum for appropriate place to ask questions. By contrast, qubes-issues is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
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 important information. Without this information, the issue is likely to be incomplete. (If certain sections are not applicable, you may remove them, but 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
If your issue is not actionable, please see Help, Support, Mailing Lists, and Forum for the appropriate place to post it. If your issue would be about more than one thing, file them as separate issues instead. This means we should generally not try to use a single issue as a "meta" or "epic" issue that exists only to group, contain, or track other issues. Instead, when there is a need to group multiple related issues together, use projects.
This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see the issue tracker is not a discussion forum).
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. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. 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 "Subscribe" button at the side or 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 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
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. A
great way to do this is by generating and submitting a Hardware Compatibility
List (HCL) report, then
linking to it in your issue. You may also need to use 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 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 repository, then to the appropriate stable repository. If you so choose, you can test the fix while it's in the 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.
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
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.