Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-05-02 06:46:11 -04:00
Code Issues Projects Releases Packages Wiki Activity

Wrap text and miscellaneous cleanup

Browse source
This commit is contained in:
Andrew David Wong 2021-06-18 06:25:06 -07:00
parent e451f92cde
commit 07c130df00
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
21 changed files with 1845 additions and 1022 deletions
Download patch file Download diff file Expand all files Collapse all files

92
introduction/code-of-conduct.md
View file

@ -8,19 +8,35 @@ title: Code of Conduct
## Introduction
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project.
It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living.
Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world.
It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself.
We welcome you to view the [history of changes](https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md) to this document and the [discussion](https://github.com/QubesOS/qubes-issues/issues/2163) leading to its creation.
This Code of Conduct is a collaborative, evolving document that attempts to
transparently set out a public set of standards regarding appropriate conduct
in the Qubes OS Project. It is *not* intended to be a statement or endorsement,
whether implicit or explicit, of any particular political or philosophical
attitude, belief, or way of living. Rather, it is an attempt to find a
reasonable middle ground among the inevitable disagreements regarding free
expression that arise in a large, diverse community of people from around the
world. It is intended to be a practical means of serving the best interests of
our users, contributors, and the project itself. We welcome you to view the
[history of
changes](https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md)
to this document and the
[discussion](https://github.com/QubesOS/qubes-issues/issues/2163) leading to
its creation.
## Our Pledge
The Qubes OS project creates a reasonably secure OS. In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, sexual identity and orientation, or other characteristic.
The Qubes OS project creates a reasonably secure OS. In the interest of
fostering an open and welcoming environment, we as contributors and maintainers
pledge to make participation in our project and our community a harassment-free
experience for everyone, regardless of age, body size, disability, ethnicity,
gender identity and expression, level of experience, nationality, personal
appearance, race, religion, sexual identity and orientation, or other
characteristic.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
Examples of behavior that contributes to creating a positive environment
include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
@ -30,36 +46,72 @@ Examples of behavior that contributes to creating a positive environment include
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- The use of sexualized language or imagery and unwelcome sexual attention or
advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Reinforcing stereotypical models for illustration of non-technical users (e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of Conduct](http://citizencodeofconduct.org/)
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
- Reinforcing stereotypical models for illustration of non-technical users
(e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of
Conduct](http://citizencodeofconduct.org/)
- Publishing others' private information, such as a physical or electronic
address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
(Please also see our [discussion guidelines](/support/#discussion-guidelines).)
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. This action can include removing, editing, or rejecting comments, commits, code, wiki edits, issues, and other contributions, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior. This action can include
removing, editing, or rejecting comments, commits, code, wiki edits, issues,
and other contributions, or to ban temporarily or permanently any contributor
for other behaviors that they deem inappropriate, threatening, offensive, or
harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an
appointed representative at an online or offline event. Representation of a
project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project CoC team at `mods@qubes-os.org`. The project CoC team is the [Marek Marczykowski-Górecki](/team/#marek-marczykowski-g%C3%B3recki), [Andrew David Wong](/team/#andrew-david-wong), and [Michael Carbone](/team/#michael-carbone). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident, and will ensure reporter, reported and all others impacted are regularly updated through the process. Further details of specific enforcement policies may be posted separately.
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project CoC team at `mods@qubes-os.org`. The project
CoC team is the [Marek
Marczykowski-Górecki](/team/#marek-marczykowski-g%C3%B3recki), [Andrew David
Wong](/team/#andrew-david-wong), and [Michael Carbone](/team/#michael-carbone).
All complaints will be reviewed and investigated and will result in a response
that is deemed necessary and appropriate to the circumstances. The project team
is obligated to maintain confidentiality with regard to the reporter of an
incident, and will ensure reporter, reported and all others impacted are
regularly updated through the process. Further details of specific enforcement
policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## A Note on Trust
Expect all contributions to be reviewed with some amount of healthy adversarial skepticism, regardless of your perceived standing in the community.
This is a security project, and allowing ourselves to get complacent while reviewing code simply because it comes from a well-known party would not be in the best interest of the project.
Please try not to get offended if you perceive your contributions as being met with distrust -- we are most definitely thankful and appreciative of your efforts, but must also remain vigilant in order to ensure continued quality and safeguard against potential sabotage.
Expect all contributions to be reviewed with some amount of healthy adversarial
skepticism, regardless of your perceived standing in the community. This is a
security project, and allowing ourselves to get complacent while reviewing code
simply because it comes from a well-known party would not be in the best
interest of the project. Please try not to get offended if you perceive your
contributions as being met with distrust -- we are most definitely thankful and
appreciative of your efforts, but must also remain vigilant in order to ensure
continued quality and safeguard against potential sabotage.
## Attribution
The initial published version of this Code of Conduct was adapted from the [Contributor Covenant, version 1.4](https://contributor-covenant.org/version/1/4) and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
The initial published version of this Code of Conduct was adapted from the
[Contributor Covenant, version
1.4](https://contributor-covenant.org/version/1/4) and the [Rust Code of
Conduct](https://www.rust-lang.org/en-US/conduct.html).

25
introduction/contributing.md
View file

@ -15,33 +15,36 @@ ways in which you can help:
* Audit the [source code](/doc/source-code/)
* [Report security issues](/security/)
* [Send patches](/doc/source-code/#how-to-send-patches) to fix bugs or implement features
* [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/)
* [Test new releases and updates](/doc/testing/)
* Submit [HCL reports](/doc/hcl/) for your hardware
* Record [video tours](/video-tours/)
* Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes, installer themes, wallpapers, etc.)
* Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes,
installer themes, wallpapers, etc.)
* [Write and edit the documentation](/doc/doc-guidelines)
* [Donate](/donate/) to the project
* If you represent an organization, become a [Qubes partner](/partners/)
* Add a [Qubes download mirror](/downloads/mirrors/)
* Answer questions and discuss Qubes on the [mailing lists](/support/) and [forum](/support/#forum)
* Answer questions and discuss Qubes on the [mailing lists](/support/) and
[forum](/support/#forum)
* Engage with us on social media:
* Follow us on [Twitter](https://twitter.com/QubesOS)
* Join us on [Reddit](https://www.reddit.com/r/Qubes/)
* Like us on [Facebook](https://www.facebook.com/QubesOS)
* Connect with us on [LinkedIn](https://www.linkedin.com/company/qubes-os/)
* And last but not least, tell your friends and colleagues about how Qubes
can help them secure their digital lives!
* And last but not least, tell your friends and colleagues about how Qubes can
help them secure their digital lives!
Contributing Code
-----------------
If you're interested in contributing code, the best starting point is to have a
look at our [GitHub issues](https://github.com/QubesOS/qubes-issues/issues) to see which tasks are the most urgent. You can
filter issues depending on your interest and experience. For example, here are
some common issue labels:
look at our [GitHub issues](https://github.com/QubesOS/qubes-issues/issues) to
see which tasks are the most urgent. You can filter issues depending on your
interest and experience. For example, here are some common issue labels:
* [Help wanted](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
* [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
@ -52,7 +55,7 @@ some common issue labels:
Before you engage in an activity that will take you a significant amount of
time, like implementing a new feature, it's always good to contact us first,
preferably via the [qubes-devel](/support/#qubes-devel) mailing list. Once we've worked out the
details, we'll add you to our [Community-Developed Feature Tracker](/qubes-issues/). We'll then
be grateful to [receive your patch](/doc/source-code/#how-to-send-patches).
preferably via the [qubes-devel](/support/#qubes-devel) mailing list. Once
we've worked out the details, we'll be grateful to [receive your
patch](/doc/source-code/#how-to-send-patches).

83
introduction/privacy.md
View file

@ -9,17 +9,41 @@ redirect_from:
title: Privacy Policy
---
The short version is that we try to respect your privacy as much as possible. We absolutely do not sell any user data. In fact, we go out of our way to help you keep your data private from everyone, including us. For example, from the moment you [install Qubes OS](/doc/installation-guide/), we offer to set up [Whonix](https://www.whonix.org/) so that all of your updates are routed through [Tor](https://www.torproject.org/).
The short version is that we try to respect your privacy as much as possible.
We absolutely do not sell any user data. In fact, we go out of our way to help
you keep your data private from everyone, including us. For example, from the
moment you [install Qubes OS](/doc/installation-guide/), we offer to set up
[Whonix](https://www.whonix.org/) so that all of your updates are routed
through [Tor](https://www.torproject.org/).
## Website
For the legally-required boilerplate, see [Website Privacy Policy](/website-privacy-policy/).
For the legally-required boilerplate, see [Website Privacy
Policy](/website-privacy-policy/).
This is just a static website generated with Jekyll and hosted from GitHub Pages. We try to use as little JavaScript as possible. We host all resources locally (no third-party CDNs) so that you only have to connect to one domain. This site should be easy to browse using Tor Browser and with scripts blocked. We also have an [onion service](http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/) (access is not logged). We even go out of our way to make it easy to download [this website's git repo](https://github.com/QubesOS/qubesos.github.io), including all the website source code, so that you can host this entire site from your own local machine offline. Better yet, we've specifically written all of the [documentation](/doc/) in Markdown so that the plain text can be enjoyed from the comfort of your terminal. Here's the [repo](https://github.com/QubesOS/qubes-doc). (By the way, Git tags on our repos are PGP-signed so you can [verify](/doc/verifying-signatures) the authenticity of the content.) Obviously, we don't use any ads or trackers, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. See [FAQ: Should I trust this website?](/faq/#should-i-trust-this-website)
This is just a static website generated with Jekyll and hosted from GitHub
Pages. We try to use as little JavaScript as possible. We host all resources
locally (no third-party CDNs) so that you only have to connect to one domain.
This site should be easy to browse using Tor Browser and with scripts blocked.
We also have an [onion
service](http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/)
(access is not logged). We even go out of our way to make it easy to download
[this website's git repo](https://github.com/QubesOS/qubesos.github.io),
including all the website source code, so that you can host this entire site
from your own local machine offline. Better yet, we've specifically written all
of the [documentation](/doc/) in Markdown so that the plain text can be enjoyed
from the comfort of your terminal. Here's the
[repo](https://github.com/QubesOS/qubes-doc). (By the way, Git tags on our
repos are PGP-signed so you can [verify](/doc/verifying-signatures) the
authenticity of the content.) Obviously, we don't use any ads or trackers, but
this is still a public website, so man-in-the-middle attacks and such are
always a possibility. Please be careful. See [FAQ: Should I trust this
website?](/faq/#should-i-trust-this-website)
## Update Servers & Repositories
We provide repositories at <https://yum.qubes-os.org> and <https://deb.qubes-os.org>.
We provide repositories at <https://yum.qubes-os.org> and
<https://deb.qubes-os.org>.
We collect the following types of data:
@ -27,36 +51,47 @@ We collect the following types of data:
- The number of requests from each IPv4 address
- Standard server access and error logs
We collect this data solely for the purpose of generating [Qubes userbase statistics](/statistics/).
The data is retained for up to two months so that we can re-calculate the previous month's statistics in case anything goes wrong.
After that, the data is permanently and securely destroyed.
We never sell the data to anyone or share it with any third party.
We collect this data solely for the purpose of generating [Qubes userbase
statistics](/statistics/). The data is retained for up to two months so that we
can re-calculate the previous month's statistics in case anything goes wrong.
After that, the data is permanently and securely destroyed. We never sell the
data to anyone or share it with any third party.
If you would like to hide your IP address from us, we strongly encourage it and are happy to help you do so!
Simply choose the Whonix option to route all of your updates over Tor [when installing Qubes OS](/doc/installation-guide/).
If you would like to hide your IP address from us, we strongly encourage it and
are happy to help you do so! Simply choose the Whonix option to route all of
your updates over Tor [when installing Qubes OS](/doc/installation-guide/).
## Onion Services
We provide an [onion service](http://www.qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion) for the website and onion service mirrors of the repositories.
Access to these servers is not logged.
We provide an [onion
service](http://www.qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion)
for the website and onion service mirrors of the repositories. Access to these
servers is not logged.
## Download Mirrors
There are also other third-party [download mirrors](/downloads/#mirrors) hosted by volunteers.
We have no control over or access to data collected by these mirrors.
There are also other third-party [download mirrors](/downloads/#mirrors) hosted
by volunteers. We have no control over or access to data collected by these
mirrors.
## Qubes OS
We have specifically designed Qubes OS so that it is not possible to collect any data directly from Qubes OS installations.
In other words, Qubes OS does not have the ability to "phone home" and is intentionally architected to forbid that from happening.
This is mainly because we have ensured that dom0 has no network access.
We have specifically designed Qubes OS so that it is not possible to collect
any data directly from Qubes OS installations. In other words, Qubes OS does
not have the ability to "phone home" and is intentionally architected to forbid
that from happening. This is mainly because we have ensured that dom0 has no
network access.
We don't want the ability collect any data directly from Qubes OS installations, because if anyone has that power, then the system is not secure.
We all use Qubes OS ourselves as a daily driver for our work and personal lives, so our interests are aligned with yours.
We want privacy too!
Thankfully, Qubes OS is free and open-source software, so you don't have to take our word for it.
We don't want the ability collect any data directly from Qubes OS
installations, because if anyone has that power, then the system is not secure.
We all use Qubes OS ourselves as a daily driver for our work and personal
lives, so our interests are aligned with yours. We want privacy too!
Thankfully, Qubes OS is free and open-source software, so you don't have to
take our word for it.
Of course, third-party software (including other operating systems) running inside of qubes may not be as privacy-respecting, so please be mindful of what you install.
We have no control over such third-party software.
Of course, third-party software (including other operating systems) running
inside of qubes may not be as privacy-respecting, so please be mindful of what
you install. We have no control over such third-party software.
For more information, please see [FAQ: How does Qubes OS provide privacy?](/faq/#how-does-qubes-os-provide-privacy)
For more information, please see [FAQ: How does Qubes OS provide
privacy?](/faq/#how-does-qubes-os-provide-privacy)

211
introduction/reporting-bugs.md
View file

@ -15,125 +15,184 @@ ref: 121
title: Reporting Bugs and Other Issues
---
All issues 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), our GitHub issue tracker.
If you're looking for help, please see [Help, Support, Mailing Lists, and Forum](/support/).
All issues 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), our GitHub
issue tracker. If you're looking for help, please see [Help, Support, Mailing
Lists, and Forum](/support/).
## Important ##
- **To disclose a security issue confidentially, please see the [Security](/security/) page.**
- **In all other cases, please do not email individual developers about issues.**
- **Please note that many issues can be resolved by reading the [documentation](/doc/).**
- **If you see something that should be changed in the documentation, [submit a change](/doc/doc-guidelines/).**
- **To disclose a security issue confidentially, please see the
[Security](/security/) page.**
- **In all other cases, please do not email individual developers about
issues.**
- **Please note that many issues can be resolved by reading the
[documentation](/doc/).**
- **If you see something that should be changed in the documentation, [submit a
change](/doc/doc-guidelines/).**
## Search Tips ##
[Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue)
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](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
[Search both open and closed
issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue)
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](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
[Search using labels.](https://github.com/QubesOS/qubes-issues/labels)
For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For
example, you can search issues by priority
([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker),
[critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical),
[major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and
by component
([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22),
[manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+),
[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 **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`).
Only Qubes team members can apply labels. Every issue must have exactly one
**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 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](/support/)).
You can simply link to the relevant issue in your discussion post.
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](/support/)). 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](#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.
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](#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](https://github.com/QubesOS/qubes-issues/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](/support/) for appropriate place to ask questions.
By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
[qubes-issues](https://github.com/QubesOS/qubes-issues/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](/support/) for appropriate place to ask
questions. By contrast,
[qubes-issues](https://github.com/QubesOS/qubes-issues/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.)
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.
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](/support/) 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](https://github.com/QubesOS/qubes-issues/projects).
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
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](https://github.com/QubesOS/qubes-issues/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](#the-issue-tracker-is-not-a-discussion-forum)).
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](#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.
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.
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](/doc/how-to-copy-from-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](/doc/hcl/#generating-and-submitting-new-reports), 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](/doc/testing/) repository, please reference the appropriate issue in 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!
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](/doc/how-to-copy-from-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](/doc/hcl/#generating-and-submitting-new-reports), 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](/doc/testing/) repository, please reference the appropriate issue in
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 ###
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.
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](/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.
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
[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.
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.
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.
## See also ##