diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 0146fe3a..dd72699a 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -15,7 +15,7 @@ A workflow for developing Qubes OS+ First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide assumes you're using qubes-builder to build Qubes. -# Repositories and committing Code +## Repositories and committing Code Qubes is split into a bunch of git repos. These are all contained in the `qubes-src` directory under qubes-builder. Subdirectories there are separate diff --git a/developer/building/qubes-builder.md b/developer/building/qubes-builder.md index 572b9866..035a36d3 100644 --- a/developer/building/qubes-builder.md +++ b/developer/building/qubes-builder.md @@ -24,6 +24,7 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou - git - createrepo - rpm-build +- dnf-plugins-core - make - wget - rpmdevtools diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index aa5272f6..fe9fb452 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -15,7 +15,7 @@ title: Qubes ISO building Build Environment ----------------- -Fedora 32 has been successfully used to build Qubes R4.1 with the below steps. +Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below steps. Other rpm-based operating systems may also work. Travis-CI uses Ubuntu 18.04 to perform test builds, except it can not test the `./setup` script. @@ -29,13 +29,13 @@ sudo setenforce 0 ~~~ -In `dom0`, install the Fedora 32 template if you don't already have it. +In `dom0`, install the Fedora 36 (or 37) template if you don't already have it. ~~~ -sudo qubes-dom0-update qubes-template-fedora-32 +sudo qubes-dom0-update qubes-template-fedora-36 ~~~ -Create a standalone AppVM from the Fedora 32 template. +Create a standalone AppVM from the Fedora template. Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional. It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build. Likewise, more memory (up to 16 GB) can help. diff --git a/developer/code/coding-style.md b/developer/code/coding-style.md index 5bc1dec5..beb616a2 100644 --- a/developer/code/coding-style.md +++ b/developer/code/coding-style.md @@ -123,7 +123,7 @@ Source Code management (Git) guidelines - Use git to maintain all code for Qubes project. -- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it. +- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it. - Qubes code is divided into many git repositories. There are several reasons for that: - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. @@ -169,7 +169,7 @@ Security coding guidelines Python-specific guidelines -------------------------- -- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page. +- Please follow the guidelines [here](https://peps.python.org/pep-0008/), unless they were in conflict with what is written on this page. C and C++ specific guidelines ----------------------------- diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index 3fd4ed24..38e4aca2 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -121,7 +121,7 @@ Tests are also compatible with nose2 test runner, so you can use this instead: sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd ``` -This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](http://open.qa/). +This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](https://open.qa/). ### Unit testing inside a VM @@ -248,7 +248,7 @@ class SomeTestCase(unittest.TestCase): **Tests:** Manually testing Qubes OS and its installation is a time-consuming process. -We use [OpenQA](http://open.qa/) to automate this process. +We use [OpenQA](https://open.qa/) to automate this process. It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses. Then, it checks the output to see whether various tests were passed, e.g. by comparing the virtual screen output to screenshots of a successful installation. diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index d6fc2dff..9c54619d 100644 --- a/developer/debugging/vm-interface.md +++ b/developer/debugging/vm-interface.md @@ -34,7 +34,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple - `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` - `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page. - `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" -- `/qubes-ip - IP address for this VM (only when VM has netvm set) +- `/qubes-ip` - IP address for this VM (only when VM has netvm set) - `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) - `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) - `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) diff --git a/developer/general/documentation-style-guide.md b/developer/general/documentation-style-guide.md index 45064074..84881663 100644 --- a/developer/general/documentation-style-guide.md +++ b/developer/general/documentation-style-guide.md @@ -13,88 +13,52 @@ title: Documentation style guide _Also see [how to edit the documentation](/doc/how-to-edit-the-documentation/)._ -Qubes OS documentation pages are stored as plain text Markdown files in the -[qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and -regularly pulling from this repo, users can maintain their own up-to-date -offline copy of all Qubes documentation rather than relying solely on the web. +Qubes OS documentation pages are stored as plain text Markdown files in the [qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web. -The documentation is a volunteer community effort. People like you are -constantly working to make it better. If you notice something that can be fixed -or improved, please [edit the -documentation](/doc/how-to-edit-the-documentation/)! +The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please [edit the documentation](/doc/how-to-edit-the-documentation/)! -This page explains the standards we follow for writing, formatting, and -organizing the documentation. Please follow these guidelines and conventions -when editing the documentation. For the standards governing the website as a -whole, please see the [website style guide](/doc/website-style-guide). +This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the documentation. For the standards governing the website as a whole, please see the [website style guide](/doc/website-style-guide). ## Markdown conventions -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please observe the following style conventions. If you're -not familiar with Markdown syntax, -[this](https://daringfireball.net/projects/markdown/) is a great resource. +All the documentation is written in Markdown for maximum accessibility. When making contributions, please observe the following style conventions. If you're not familiar with Markdown syntax, [this](https://daringfireball.net/projects/markdown/) is a great resource. ### Hyperlink syntax -Use non-reference-style links like `[website](https://example.com/)`. Do *not* -use reference-style links like `[website][example]`, `[website][]` or -`[website]`. This facilitates the localization process. +Use non-reference-style links like `[website](https://example.com/)`. Do *not* use reference-style links like `[website][example]`, `[website][]` or `[website]`. This facilitates the localization process. ### Relative vs. absolute links -Always use relative rather than absolute paths for internal website links. For -example, use `/doc/documentation-style-guide/` instead of -`https://www.qubes-os.org/doc/documentation-style-guide/`. +Always use relative rather than absolute paths for internal website links. For example, use `/doc/documentation-style-guide/` instead of `https://www.qubes-os.org/doc/documentation-style-guide/`. You may use absolute URLs in the following cases: - External links -- URLs that appear inside code blocks (e.g., in comments and document - templates, and the plain text reproductions of [QSBs](/security/qsb/) and - [Canaries](/security/canary/)), since they're not hyperlinks -- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part - of the website itself but rather of the auxiliary infrastructure supporting - the website +- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of [QSBs](/security/qsb/) and [Canaries](/security/canary/)), since they're not hyperlinks +- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part of the website itself but rather of the auxiliary infrastructure supporting the website -This rule is important because using absolute URLs for internal website links -breaks: +This rule is important because using absolute URLs for internal website links breaks: - Serving the website offline - Website localization - Generating offline documentation -- Automatically redirecting Tor Browser visitors to the correct page on the - onion service mirror +- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror ### Image linking -See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) -for the required syntax. This will make the image a hyperlink to the image -file, allowing the reader to click on the image in order to view the full image -by itself. This is important. Following best practices, our website has a -responsive design, which allows the website to render appropriately across all -screen sizes. When viewing this page on a smaller screen, such as on a mobile -device, the image will automatically shrink down to fit the screen. If visitors -cannot click on the image to view it in full size, then, depending on their -device, they may have no way see the details in the image clearly. +See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly. -In addition, make sure to link only to images in the -[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do -not attempt to link to images hosted on other websites. +In addition, make sure to link only to images in the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do not attempt to link to images hosted on other websites. ### HTML and CSS -Do not write HTML inside Markdown documents (except in rare, unavoidable cases, -such as alerts). In particular, never include HTML or CSS for styling, -formatting, or white space control. That belongs in the (S)CSS files instead. +Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as [alerts](#alerts)). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead. ### Headings -Do not use `h1` headings (single `#` or `======` underline). These are -automatically generated from the `title:` line in the YAML front matter. +Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML front matter. -Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use -underlining syntax (`-----`). +Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use underlining syntax (`-----`). ### Indentation @@ -102,49 +66,131 @@ Use spaces instead of tabs. Use hanging indentations where appropriate. ### Lists -If appropriate, make numerals in numbered lists match between Markdown source -and HTML output. Some users read the Markdown source directly, and this makes -numbered lists easier to follow. +If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow. ### Code blocks -When writing code blocks, use [syntax -highlighting](https://github.github.com/gfm/#info-string) where possible (see -[here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) -for a list of supported languages). Use `[...]` for anything omitted. +When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where possible (see [here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) for a list of supported languages). Use `[...]` for anything omitted. ### Line wrapping -Hard wrap Markdown lines at 80 characters, unless the line can't be broken -(e.g., code or a URL). +Do not hard wrap text, except where necessary (e.g., inside code blocks). + +### Do not use Markdown syntax for styling + +For example, there is a common temptation to use block quotations (created by beginning lines with the `>` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.: + +``` +> Note: This is an important note! +``` + +This renders as: + +> Note: This is an important note! + +There are two problems with this: + +1. It is a violation of the [separation of content and presentation](https://en.wikipedia.org/wiki/Separation_of_content_and_presentation), since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS. + +2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You're just telling the reader to note something and trying to draw their attention to your note visually.) + +Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using [alerts](#alerts). Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,: + +``` +**Note:** This is an important note. +``` + +This renders as: + +**Note:** This is an important note. + +### Alerts + +Alerts are sections of HTML used to draw the reader's attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause [alert fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons: + +``` + + + + + + + +``` + +These render as: + + + + + + + + ## Writing guidelines ### Correct use of terminology -Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). -Use these terms consistently and accurately throughout your writing. +Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). Use these terms consistently and accurately throughout your writing. ### Sentence case in headings -Use sentence case (rather than title case) in headings for the reasons -explained -[here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/). -In particular, since the authorship of the Qubes documentation is decentralized -and widely distributed among users from around the world, many contributors -come from regions with different conventions for implementing title case, not -to mention that there are often differing style guide recommendations even -within a single region. It is much easier for all of us to implement sentence -case consistently across our growing body of pages, which is very important for -managing the ongoing maintenance burden and sustainability of the -documentation. +Use sentence case (rather than title case) in headings for the reasons explained [here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/). In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation. ### Writing command-line examples When providing command-line examples: -- Tell the reader where to open a terminal (dom0 or a specific domU), and show - the command along with its output (if any) in a code block, e.g.: +- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: ~~~markdown Open a terminal in dom0 and run: @@ -155,12 +201,9 @@ When providing command-line examples: ``` ~~~ -- Precede each command with the appropriate command prompt: At a minimum, the - prompt should contain a trailing `#` (for the user `root`) or `$` (for other - users) on Linux systems and `>` on Windows systems, respectively. +- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively. -- Don't try to add comments inside the code block. For example, *don't* do - this: +- Don't try to add comments inside the code block. For example, *don't* do this: ~~~markdown Open a terminal in dom0 and run: @@ -173,14 +216,11 @@ When providing command-line examples: ``` ~~~ - The `#` symbol preceding each comment is ambiguous with a root command - prompt. Instead, put your comments *outside* of the code block in normal - prose. + The `#` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose. ### Variable names in commands -Syntactically distinguish variables in commands. For example, this is -ambiguous: +Syntactically distinguish variables in commands. For example, this is ambiguous: $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm @@ -194,135 +234,53 @@ Note that we syntactically distinguish variables in three ways: 2. Using underscores (`_`) instead of spaces between words 3. Using all capital letters -We have observed that many novices make the mistake of typing the surrounding -angled brackets (`< >`) on the command line, even after substituting the -desired real value between them. Therefore, in documentation aimed at novices, -we also recommend clarifying that the angled brackets should not be typed. This -can be accomplished in one of several ways: +We have observed that many novices make the mistake of typing the surrounding angled brackets (`< >`) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways: - Explicitly say something like "without the angled brackets." -- Provide an example command using real values that excludes the angled - brackets. -- If you know that almost all users will want to use (or should use) a specific - command containing all real values and no variables, you might consider - providing exactly that command and forgoing the version with variables. - Novices may not realize which parts of the command they can substitute with - different values, but if you've correctly judged that they should use the - command you've provided as is, then this shouldn't matter. +- Provide an example command using real values that excludes the angled brackets. +- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you've correctly judged that they should use the command you've provided as is, then this shouldn't matter. + +### Capitalization of "qube" + +We introduced the term ["qube"](/doc/glossary/#qube) as a user-friendly alternative to the term ["virtual machine" ("VM")](/doc/glossary/#vm) in the context of Qubes OS. Nonetheless, "qube" is a common noun like the words "compartment" and "container." Therefore, in English, "qube" follows the standard capitalization rules for common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Like other common nouns, "qube" should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of "qube" (e.g., "Qubes can be shut down...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, [Qubes OS](/doc/glossary/#qubes-os), or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity. + +Many people feel a strong temptation to capitalize the word "qube" all the time, like a proper noun, perhaps because it's a new and unfamiliar term that's closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it's not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, "blockchain" is a relatively recent technical term that's a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn't change the way we capitalize sentences like, "John sat under a tree." Intuitively, it makes sense that the addition and removal of objects from the world shouldn't cause published books to become orthographicallly incorrect while sitting on their shelves. + +Accordingly, the reason "qube" is a common noun rather than a proper noun is because it doesn't refer to any one specific thing (in this case, any one specific virtual machine). Rather, it's the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called "qubes.") + +I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren't tempted to treat words like "neighborhood" or "street" as proper nouns (unless, of course, they're part of a name, like "Acorn Street"). Again, while this might seem odd because "qube" is a new word that we invented, that doesn't change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn't have any words at all). We treat "telephone," "computer," "network," "program," and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn't allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity. + +### English language conventions + +For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.) ## Organizational guidelines ### Do not duplicate documentation -Duplicating documentation is almost always a bad idea. There are many reasons -for this. The main one is that almost all documentation has to be updated as -some point. When similar documentation appears in more than one place, it is -very easy for it to get updated in one place but not the others (perhaps -because the person updating it doesn't realize it's in more than once place). -When this happens, the documentation as a whole is now inconsistent, and the -outdated documentation becomes a trap, especially for novice users. Such traps -are often more harmful than if the documentation never existed in the first -place. The solution is to **link** to existing documentation rather than -duplicating it. There are some exceptions to this policy (e.g., information -that is certain not to change for a very long time), but they are rare. +Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn't realize it's in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare. ### Core vs. external documentation -Core documentation resides in the [Qubes OS Project's official -repositories](https://github.com/QubesOS/), mainly in -[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can -be anywhere else (such as forums, community websites, and blogs), but there is -an especially large collection in the [Qubes -Community](https://github.com/Qubes-Community) project. External documentation -should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). -If you've written a piece of documentation that is not appropriate for -[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit -it to the [Qubes Community](https://github.com/Qubes-Community) project -instead. However, *linking* to external documentation from -[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, -the maintainers of the [Qubes Community](https://github.com/Qubes-Community) -project should regularly submit PRs against the documentation index (see [How -to edit the documentation -index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) -to add and update Qubes Community links in the ["External -documentation"](/doc/#external-documentation) section of the documentation -table of contents. +Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project. External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Community](https://github.com/Qubes-Community) project should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents. -The main difference between **core** (or **official**) and **external** (or -**community** or **unofficial**) documentation is whether it documents software -that is officially written and maintained by the Qubes OS Project. The purpose -of this distinction is to keep the core docs maintainable and high-quality by -limiting them to the software output by the Qubes OS Project. In other words, -we take responsibility for documenting all of the software we put out into the -world, but it doesn't make sense for us to take on the responsibility of -documenting or maintaining documentation for anything else. For example, Qubes -OS may use a popular Linux distribution for an official -[TemplateVM](/doc/templates/). However, it would not make sense for a -comparatively small project like ours, with modest funding and a lean -workforce, to attempt to document software belonging to a large, richly-funded -project with an army of paid and volunteer contributors, especially when they -probably already have documentation of their own. This is particularly true -when it comes to Linux in general. Although many users who are new to Qubes are -also new to Linux, it makes absolutely no sense for our comparatively tiny -project to try to document Linux in general when there is already a plethora of -documentation out there. +The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there. -Many contributors do not realize that there is a significant amount of work -involved in *maintaining* documentation after it has been written. They may -wish to write documentation and submit it to the core docs, but they see only -their own writing process and fail to consider that it will have to be kept -up-to-date and consistent with the rest of the docs for years afterward. -Submissions to the core docs also have to [undergo a review -process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before -being merged, which takes up valuable time from the team. We aim to maintain -high quality standards for the core docs (style and mechanics, formatting), -which also takes up a lot of time. If the documentation involves anything -external to the Qubes OS Project (such as a website, platform, program, -protocol, framework, practice, or even a reference to a version number), the -documentation is likely to become outdated when that external thing changes. -It's also important to periodically review and update this documentation, -especially when a new Qubes release comes out. Periodically, there may be -technical or policy changes that affect all the core documentation. The more -documentation there is relative to maintainers, the harder all of this will be. -Since there are many more people who are willing to write documentation than to -maintain it, these individually small incremental additions amount to a -significant maintenance burden for the project. +Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to [undergo a review process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It's also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project. -On the positive side, we consider the existence of community documentation to -be a sign of a healthy ecosystem, and this is quite common in the software -world. The community is better positioned to write and maintain documentation -that applies, combines, and simplifies the official documentation, e.g., -tutorials that explain how to install and use various programs in Qubes, how to -create custom VM setups, and introductory tutorials that teach basic Linux -concepts and commands in the context of Qubes. In addition, just because the -Qubes OS Project has officially written and maintains some flexible framework, -such as `qrexec`, it does not make sense to include every tutorial that says -"here's how to do something cool with `qrexec`" in the core docs. Such -tutorials generally also belong in the community documentation. +On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as `qrexec`, it does not make sense to include every tutorial that says "here's how to do something cool with `qrexec`" in the core docs. Such tutorials generally also belong in the community documentation. -See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more -background information. +See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more background information. ### Release-specific documentation -*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending -changes to this policy.* +*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending changes to this policy.* -We maintain only one set of documentation for Qubes OS. We do not maintain a -different set of documentation for each release of Qubes. Our single set of -Qubes OS documentation is updated on a continual, rolling basis. Our first -priority is to document all **current, stable releases** of Qubes. Our second -priority is to document the next, upcoming release (if any) that is currently -in the beta or release candidate stage. +We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. -In cases where a documentation page covers functionality that differs -considerably between Qubes OS releases, the page should be subdivided into -clearly-labeled sections that cover the different functionality in different -releases (examples below). +In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different releases (examples below). -In general, avoid mentioning specific Qubes versions in the body text of -documentation, as these references rapidly go out of date and become misleading -to readers. +In general, avoid mentioning specific Qubes versions in the body text of documentation, as these references rapidly go out of date and become misleading to readers. #### Incorrect Example @@ -381,65 +339,17 @@ general `qubes-baz` command: Once you foo, make sure to close the baz before fooing the next bar. ``` -Subdividing the page into clearly-labeled sections for each release has several -benefits: +Subdividing the page into clearly-labeled sections for each release has several benefits: -- It preserves good content for older (but still supported) releases. Many - documentation contributors are also people who prefer to use the latest - release. Many of them are tempted to *replace* existing content that applies - to an older, supported release with content that applies only to the latest - release. This is somewhat understandable. Since they only use the latest - release, they may be focused on their own experience, and they may even - regard the older release as deprecated, even when it's actually still - supported. However, allowing this replacement of content would do a great - disservice to those who still rely on the older, supported release. In many - cases, these users value the stability and reliability of the older, - supported release. With the older, supported release, there has been more - time to fix bugs and make improvements in both the software and the - documentation. Consequently, much of the documentation content for this - release may have gone through several rounds of editing, review, and - revision. It would be a tragedy for this content to vanish while the very set - of users who most prize stability and reliability are depending on it. -- It's easy for readers to quickly find the information they're looking for, - since they can go directly to the section that applies to their release. -- It's hard for readers to miss information they need, since it's all in one - place. In the incorrect example, information that the reader needs could be - in any paragraph in the entire document, and there's no way to tell without - reading the entire page. In the correct example, the reader can simply skim - the headings in order to know which parts of the page need to be read and - which can be safely ignored. The fact that some content is repeated in the - two release-specific sections is not a problem, since no reader has to read - the same thing twice. Moreover, as one release gets updated, it's likely that - the documentation for that release will also be updated. Therefore, content - that is initially duplicated between release-specific sections will not - necessarily stay that way, and this is a good thing: We want the - documentation for a release that *doesn't* change to stay the same, and we - want the documentation for a release that *does* change to change along with - the software. -- It's easy for documentation contributors and maintainers to know which file - to edit and update, since there's only one page for all Qubes OS releases. - Initially creating the new headings and duplicating content that applies to - both is only a one-time cost for each page, and many pages don't even require - this treatment, since they apply to all currently-supported Qubes OS - releases. +- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it's actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it. +- It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their release. +- It's hard for readers to miss information they need, since it's all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it's likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn't* change to stay the same, and we want the documentation for a release that *does* change to change along with the software. +- It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS releases. -By contrast, an alternative approach, such as segregating the documentation -into two different branches, would mean that contributions that apply to both -Qubes releases would only end up in one branch, unless someone remembered to -manually submit the same thing to the other branch and actually made the effort -to do so. Most of the time, this wouldn't happen. When it did, it would mean a -second pull request that would have to be reviewed. Over time, the different -branches would diverge in non-release-specific content. Good general content -that was submitted only to one branch would effectively disappear once that -release was deprecated. (Even if it were still on the website, no one would -look at it, since it would explicitly be in the subdirectory of a deprecated -release, and there would be a motivation to remove it from the website so that -search results wouldn't be populated with out-of-date information.) +By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn't happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.) -For further discussion about release-specific documentation in Qubes, see -[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). +For further discussion about release-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). ## Git conventions -Please follow our [Git commit message -guidelines](/doc/coding-style/#commit-message-guidelines). +Please follow our [Git commit message guidelines](/doc/coding-style/#commit-message-guidelines). diff --git a/developer/general/gsod.md b/developer/general/gsod.md index fbb13eb5..d02b5163 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -6,78 +6,95 @@ ref: 242 title: Google Season of Docs (GSoD) --- -Thank you for your interest in participating in the [2021 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq). +Thank you for your interest in participating in the [2023 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2023 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq). -## 2021 Project Idea +## Instructional video series -- Qubes OS -### Qubes OS on Virtual Machines and Disposable VMs documentation - Qubes OS +### About the Qubes OS Project -#### About your organization +Qubes OS is a security-focused operating system that allows you to organize your digital life into compartments called "qubes." If one qube is compromised, the others remain safe, so a single cyberattack can no longer take down your entire digital life in one fell swoop. You can think of using Qubes OS as having many different computers on your desk for different activities but with the convenience of a single physical machine, a single unified desktop environment, and a set of tools for using qubes together securely as parts of a unified system. -Qubes OS is a free and open source operating system uniquely designed to protect the security and privacy of the user. Its architecture is built to enable a user to define different security environments ("qubes") on their computer and visually manage their interaction with each other and the world. +Qubes OS was launched in 2011 and has [received praise from security experts and organizations](/endorsements/) like Edward Snowden, the Freedom of the Press Foundation, Micah Lee, and Let's Encrypt. Qubes has [over 40,000 active users](/statistics/). From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done safely. -Qubes OS was launched in 2011 and has [received praise from security experts](https://www.qubes-os.org/endorsements/) like Edward Snowden, Bill Buddington (EFF), Isis Lovecruft (Tor Project), and Kenn White (Open Crypto Audit), and has over [30,000 active users](https://www.qubes-os.org/statistics/). +### The project's problem -From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done, safely. +There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with. -#### The Project +### The project's scope -The goal of the project is to improve the documentation related to Disposable VMs and installing Qubes OS on Virtual Machines. +This project consists of creating a series of instructional videos that satisfy the following criteria: -The current Disposable VMs documentation is scarce, inconsistent in places and is scattered across multiple pages, sometimes hard to find. This project involves consolidating it into one or few easy to find pages, covering all related subjects. It should be written in way easy to follow and understand, clearly separating basic use cases, advanced ones and internal details. The terminology should also be used consistently. +- Prospective users who are not yet familiar with Linux or Qubes OS can easily understand and follow the videos. +- The videos make a good effort to catch and keep the attention of their target audience. +- Users can follow the videos step-by-step to install Qubes OS and accomplish various tasks. +- The videos show the actual software being used (i.e., Qubes OS and any relevant software running inside of it). +- The videos are technically accurate, include security warnings where appropriate, and use terminology in a way that is consistent with the rest of the documentation (also see the [glossary](/doc/glossary/)). +- The video series is comprehensive enough that users do not need to consult the documentation or ask questions (e.g., on the forum) in order to accomplish the most popular tasks and activities. +- The videos include voice narration. (Showing the speaker is optional.) +- The quality of the videos is consistent with current standards regarding things like editing, transitions, animations, lighting, and audio quality. +- The videos are in high definition (minimum 1080p, preferably 4k). +- The videos are separated into a series, where each video is an appropriate length and is appropriately connected to the other videos in the series. +- The videos are suitable for upload and sharing on popular video-sharing and social-media platforms, such as YouTube and Twitter. (The account or channel under which the videos are uploaded is open to discussion on platforms where the Qubes OS Project does not already have a significant established presence, such as YouTube.) +- The videos are suitable for embedding in appropriate places in the Qubes documentation. (E.g., a video on how to update Qubes OS should be appropriate for appearing on the [how to update](/doc/how-to-update/) page.) +- Where possible, the videos should strive to be version-independent. (For example, a video explaining the template system should still be relevant many releases from now if the template system has not changed.) -Additionally, Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial existing installation guide for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine. This project also involves writing an installation guide that details how to install Qubes on virtual machines, and how to troubleshoot any issues that may arise. +Below is an example of the content (which is already [documented](/doc/)) that the video series is likely to cover. The precise scope of content is to be determined in consultation with the video creator. -#### Project’s scope +- Introduction to Qubes +- Selecting appropriate hardware +- How to install Qubes OS +- First steps after installing +- How to organize your qubes +- How to update +- How to back up, restore, and migrate +- How to copy and paste text (including dom0) +- How to copy and move files (including dom0) +- How to install software +- How to use and customize disposables +- How to enter fullscreen mode +- How to use devices (including block storage, USB, PCI, and optical) +- Templates: understanding, installing, uninstalling, reinstalling, etc. +- Common troubleshooting (preferably included in previous videos at appropriate points) +- The Qubes firewall +- Passwordless root +- Anti Evil Maid +- Split GPG +- U2F proxy +- YubiKey +- Whonix +- How to install and use a VPN in Qubes +- How to install and use Windows in Qubes +- Other popular topics, as time permits -The technical writer will: +The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, and Marek Marczykowski-Górecki, will supervise and support the creator. -* Review existing Disposable VM documentation +### Measuring the project's success -* Propose new documentation layout, including split between pages +We will consider the project successful if, after publication of the video series: -* Propose updated and clarified content +- Actual prospective users with no prior familiarity with Linux or Qubes OS are able to successfully install and use Qubes OS as intended by following along with the videos. +- The reception to the videos is generally positive and complaints about quality and accuracy are minimal. +- Appropriate analytics (e.g., YouTube metrics) are average or better for videos of this type (to be determined in consultation with the creator). -* Provide a new option of installation guide for users working on virtual machines. +### Timeline -* Review existing problems and provide solutions to them. +| Dates | Action items | +| -------------- | --------------------------------------- | +| March | Orientation | +| April--October | Create Qubes OS video series | +| November | Final project evaluation and case study | -* Giving a warning for using outdated versions of Qubes. -Knowledge prerequisites: +### Project budget -* Basic Qubes OS knowledge - intro, getting started. +| Expense | Amount | +| --------------------------------------- | ------- | +| Video creator (20 hours/week, 6 months) | $12,000 | +| TOTAL | $12,000 | -* Markdown. +### Additional information -* Experience in virtual boxes and machines. - -* Basic knowledge about Fedora Linux architecture. - -The project is estimated to need around 6 months, with a part-time (20hr/week) workload. Qubes OS team members focused on documentation (Michael Carbone, Andrew David Wong, Marek Marczykowski-Górecki) have committed to supporting the project. - -#### Measuring the project’s success - -We will consider the project successful if, after publication of the new documentation: - -* The Disposable VM documentation is consilidated into a few pages and easier to find. - -* Disposable VM terminology is consistent across all pages - -* There is a new installation guide detailing how to install Qubes on virtual machines (VirtualBox), complete with screenshots and troubleshooting steps where necessary. - -* There is a decrease (by ~20%) in the number of issues and questions raised for topics covered in the documentation, whether in the official Github issues tracker, the Qubes mailing list, or the Qubes community forum. - -#### Budget - -| Budget item | Amount | Running total | Note / Justification | -|-|-|-|-| -| Technical writer audit, update, and write new documentation | $12000 | $12000 | based on a 20hr/week for 6 months at 25$/hr | -| TOTAL | | $12000 | | - -#### Additional information -Qubes OS regularly participates in the Google Summer of Code and Google Season of Docs. This is our third time in a row participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes and both projects were completed -within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers, and has helped us to understand the benefits of technical writers can to our project +Qubes OS regularly participates in Google Summer of Code and Google Season of Docs. This is our third time participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes, and both projects were completed within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers and have helped us to understand the benefits that technical writers can bring to our project. While our experience in working with video creators is more limited, we are keenly aware of the benefits of high-quality video content, as well as the significant time, resources, and talent required to create it. ## Past Projects @@ -110,7 +127,7 @@ This could be helped by writing a consolidated guide with a clear list of sympto **Project**: Improve Getting Started page -**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide. +**Brief explanation**: The [Getting Started page](/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide. **Expected results**: @@ -128,14 +145,14 @@ This could be helped by writing a consolidated guide with a clear list of sympto **Project**: Rewrite qrexec documentation -**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important informations are hidden within a wall of text. +**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important information is hidden within a wall of text. Some parts are split into multiple sections, for example version specific to avoid duplication, but it doesn't help reading it. Additionally, protocol documentation describes only few specific use cases, instead of being clear and precise protocol specification. Fixing this last point may require very close cooperation with developers, as the current documentation doesn't multiple corner cases (that's one of the issue with its current shape). **Expected results**: -- Review existing [qrexec documentation](https://www.qubes-os.org/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392) +- Review existing [qrexec documentation](/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392) - Propose updated, consolidated admin documentation (policy writing, adding services) - Propose consolidated protocol specification, based on the current documentation, and cooperation with developers diff --git a/developer/general/usability-ux.md b/developer/general/usability-ux.md index 5e0c5359..b2c1f961 100644 --- a/developer/general/usability-ux.md +++ b/developer/general/usability-ux.md @@ -206,14 +206,14 @@ Clearly, cutting out something as simple as navigating through the file system c ## GNOME, KDE, and Xfce -The desktop GUIs that QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments. +The desktop GUIs that QubesOS versions 1 - 4.1 offer are [KDE](https://kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments. -This change means you should use [GTK](https://www.gtk.org/) rather than Qt for new GUIs. +This change means you should use [GTK](https://gtk.org/) rather than Qt for new GUIs. All three of these mentioned desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines), and we suggest you familiarize yourself with the platform you developing for. -- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/) -- [KDE HIG](https://techbase.kde.org/Projects/Usability/HIG) +- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/) +- [KDE HIG](https://hig.kde.org/) - [Xfce UI Guidlines](https://wiki.xfce.org/dev/hig/general) --- @@ -222,9 +222,9 @@ All three of these mentioned desktop environments have their own [human interfac Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources: -- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum -- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt +- [Learn Design Principles](https://web.archive.org/web/20180101172357/http://learndesignprinciples.com/) by Melissa Mandelbaum +- [Usability in Free Software](https://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt - [Superheroes & Villains in Design](https://vimeo.com/70030549) by Aral Balkan -- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen +- [First Rule of Usability? Don’t Listen to Users](https://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen - [10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/) by Jakob Nielsen - [Hack Design](https://hackdesign.org/) - online learning program diff --git a/developer/releases/4_2/release-notes.md b/developer/releases/4_2/release-notes.md new file mode 100644 index 00000000..0326ba19 --- /dev/null +++ b/developer/releases/4_2/release-notes.md @@ -0,0 +1,48 @@ +--- +layout: doc +title: Qubes OS 4.2.0 release notes +permalink: /doc/releases/4.2/release-notes/ +--- + +_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._ + +## New features and improvements since Qubes 4.1 + +- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982)) +- Xen upgraded to version 4.17 +- Default Debian template upgraded to Debian 12 +- Default Fedora and Debian templates use Xfce instead of GNOME ([#7784](https://github.com/QubesOS/qubes-issues/issues/7784)) +- SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239)) +- Several GUI applications rewritten, including: + - Applications Menu (also available as preview in R4.1) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677)) + - Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898)) + - Create New Qube + - Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443)) +- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985)) +- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358)) +- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855)) +- Optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415)) +- Official packages built using Qubes Builder v2 ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486)) +- Split GPG and Split SSH management in Qubes Global Settings +- Qrexec services use new qrexec policy format by default (but old format is still supported) ([#8000](https://github.com/QubesOS/qubes-issues/issues/8000)) + +For a full list, including more detailed descriptions, please see +[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed). + +## Known issues + +- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062)) + +For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes. + +## Download + +All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page. + +## Installation instructions + +See the [installation guide](/doc/installation-guide/). + +## Upgrading + +Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/). diff --git a/developer/releases/4_2/schedule.md b/developer/releases/4_2/schedule.md new file mode 100644 index 00000000..54fb6900 --- /dev/null +++ b/developer/releases/4_2/schedule.md @@ -0,0 +1,18 @@ +--- +lang: en +layout: doc +permalink: /doc/releases/4.2/schedule/ +redirect_from: +- /en/doc/releases/4.2/schedule/ +title: Qubes R4.2 release schedule +--- + +_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._ + +The table below is based on our [release schedule +policy](/doc/version-scheme/#release-schedule). + +| Date | Stage | +| ----------:| ----------------------------------------- | +| 2023-06-02 | 4.2.0-rc1 release | +| TODO | current-testing freeze before 4.2.0-rc2 | diff --git a/developer/releases/notes.md b/developer/releases/notes.md index 1be2115d..4c84571c 100644 --- a/developer/releases/notes.md +++ b/developer/releases/notes.md @@ -6,10 +6,11 @@ ref: 13 title: Release notes --- -* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) -* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) -* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) -* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) -* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) -* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) -* [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/) +- [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) +- [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) +- [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) +- [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) +- [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) +- [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) +- [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/) +- [Qubes R4.2 release notes](/doc/releases/4.2/release-notes/) diff --git a/developer/releases/schedules.md b/developer/releases/schedules.md index 6f656cf1..385ab1bf 100644 --- a/developer/releases/schedules.md +++ b/developer/releases/schedules.md @@ -6,8 +6,9 @@ ref: 15 title: Release schedules --- -* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) -* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) -* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) -* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) -* [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/) +- [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) +- [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) +- [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) +- [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) +- [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/) +- [Qubes R4.2 release schedule](/doc/releases/4.2/schedule/) diff --git a/developer/releases/version-scheme.md b/developer/releases/version-scheme.md index a530947c..a96f9ca6 100644 --- a/developer/releases/version-scheme.md +++ b/developer/releases/version-scheme.md @@ -27,6 +27,13 @@ notable exception, as upstream OSes almost always have their own release schedules.) Bug fixes are allowed in all releases, and backward-compatible changes are allowed in all major and minor releases. +Qubes OS minor releases generally include new features, new templates, and +occasionally new defaults, but they are still backward-compatible in the sense +that qubes and features that worked in the previous release still function, +though the UI may be different in some cases. In general, deprecated features +are removed only in major releases, and in-place upgrades between major versions +are not guaranteed. + Following standard practice, **version** refers to any build that has been assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By contrast, **release** refers to any version that is intended for consumption by @@ -52,47 +59,48 @@ Qubes OS. Another remix may have its own version series. ## Release versioning -Qubes OS as a whole is released from time to time. When preparing a new -release, we decide on the `.` numbers (e.g., `3.0`). We then -publish the first release candidate, `3.0-rc1`. When we feel that enough -progress has been made, we'll release `3.0-rc2` and so on. All these versions -(not yet releases) are considered unstable and not for production use. You are -welcome to [help us test](/doc/testing/) these versions. +Qubes OS as a whole is released from time to time. When preparing a new release, +we decide on the `.` numbers (e.g., `3.0`, which is short for +`3.0.0`). We then publish the first release candidate, e.g., `3.0.0-rc1`. When +we feel that enough progress has been made, we'll release `3.0.0-rc2` and so on. +All these versions (which are not yet releases) are considered unstable and are +not intended for production use. You are welcome to [help us +test](/doc/testing/) these versions. When enough progress has been made, we announce the first stable release, e.g. -`3.0.0`. This not only a version but an actual release. It is considered stable -and we commit to supporting it according to our [support +`3.0.0`. This is not only a version but an actual release. It is considered +stable, and we commit to supporting it according to our [support schedule](/doc/supported-releases/). Core components are branched at this -moment and bug fixes are backported from the master branch. Please see [help, +moment, and bug fixes are backported from the master branch. Please see [help, support, mailing lists, and forum](/support/) for places to ask questions about -stable releases. No major features and interface incompatibilities are to be +stable releases. No major features or interface incompatibilities are to be included in this release. We release bug fixes as patch releases (`3.0.1`, `3.0.2`, and so on), while backward-compatible enhancements and new features are introduced in the next minor release (e.g., `3.1`). Any backward-incompatible changes are introduced in the next major release (e.g., `4.0`). -Issues in our [issue tracker](/doc/issue-tracking/) are sorted by release -[milestones](/doc/issue-tracking/#milestones). +Please see [issue tracking](/doc/issue-tracking/) for information about how +releases are handled in the issue tracker. ## Release schedule -There is no specific schedule for releases other that more general roadmap. -When time comes, Supreme Committee declares feature freeze and tags `-rc1` and -releases ISO image. From this time on, no new features are accepted. Also a -strict time schedule kicks in. +There is no specific schedule for releases other than a general roadmap. +When the time comes, we declare a feature freeze, tag `-rc1`, and +release an ISO. From this point on, no new features are accepted, and our +schedule begins. -Each release candidate period is as follows. For the first two weeks we accept -and assign bug reports to be fixed before next release candidate. For the next -two weeks we generally focus on fixing assigned bug reports, so issues -discovered during this time may be postponed until later RC. Finally after that -there is one week of current-testing freeze, during which time no new packages -are released, in hope that they will be installed by wider user base and -tested. +Each release candidate period is as follows: For the first two weeks, we accept +and assign bug reports to be fixed before the next release candidate. For the +next two weeks, we generally focus on fixing assigned bug reports, so issues +discovered during this period may be postponed until a later RC. Finally, +there is a one week current-testing freeze, during which time no new packages +are released, in the hope that they will be installed and tested by wider user +base. -The next RC is released five weeks after the former. All packets are published -in `current` repository and the cycle starts over. There should be no less than -1 and no more than 3 release candidates before final release. +The next RC is released five weeks after the former. All packages are published +in the `current` repository, and the cycle starts over. There should always be +at least one release candidate before the final release. | Stage | Duration | | ------------------------ | --------- | @@ -100,11 +108,11 @@ in `current` repository and the cycle starts over. There should be no less than | bug fixing | two weeks | | `current-testing` freeze | one week | -Starting with second cycle (that is, after `-rc1`) two weeks into the cycle -(after primary bug-reporting period) the Supreme Committee decides whether -there should be another RC. If, based on remaining issues, the Committee -decides to release final, then the Committee agrees upon the release date, -which should be no later than a week after. +Starting with the second cycle (that is, after `-rc1`), two weeks into the cycle +(after the primary bug-reporting period), we decide whether there should be +another RC. If, based on the bugs that have been reported, we decide that the +latest RC will be designated as the stable release, then we decide on its +release date, which should be no more than one week later. [![Release cycle](/attachment/doc/release-cycle.svg)](/attachment/doc/release-cycle.svg) diff --git a/developer/system/security-critical-code.md b/developer/system/security-critical-code.md index 64dd4129..f9821666 100644 --- a/developer/system/security-critical-code.md +++ b/developer/system/security-critical-code.md @@ -15,7 +15,7 @@ Below is a list of security-critical (i.e., trusted) code components in Qubes OS A successful attack against any of these components could compromise the system's security. This code can be thought of as the Trusted Computing Base (TCB) of Qubes OS. One of the main goals of the project is to keep the TCB to an absolute minimum. -The size of the current TCB is on the order order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes. +The size of the current TCB is on the order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes. (In Windows, Linux, and Mac OSes, the amount of trusted code is typically on the order of tens of *millions* of lines of C code.) For more information, see [Qubes Security Goals](/security/goals/). diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md index e4cc5303..4feb91fb 100644 --- a/developer/system/template-implementation.md +++ b/developer/system/template-implementation.md @@ -10,6 +10,8 @@ ref: 58 title: Template implementation --- +## Block devices of a VM + Every VM has 4 block devices connected: - **xvda** – base root device (/) – details described below @@ -17,7 +19,7 @@ Every VM has 4 block devices connected: - **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below) - **xvdd** – modules.img – kernel modules and firmware -## private.img (xvdb) +### private.img (xvdb) This is mounted as /rw and here is placed all VM private data. This includes: @@ -25,9 +27,9 @@ This is mounted as /rw and here is placed all VM private data. This includes: - */usr/local* – which is symlink to /rw/usrlocal - some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local) -**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are *not* copied to the child TemplateBasedVM's `/home`. The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. +**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM [are *not* copied to the child TemplateBasedVM's `/home`](/doc/templates/#inheritance-and-persistence). The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. -## modules.img (xvdd) +### modules.img (xvdd) As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files: @@ -37,9 +39,9 @@ As the kernel is chosen in dom0, there must be some way to provide matching kern Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device. -There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom". +There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. -# Qubes TemplateVM implementation +## Qubes TemplateVM implementation TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs: @@ -50,7 +52,7 @@ There are two layers of the device-mapper snapshot device; the first one enables ![TemplateSharing2.png](/attachment/doc/TemplateSharing2.png) -## Snapshot device in Dom0 +### Snapshot device in Dom0 This device consists of: @@ -61,7 +63,7 @@ The above is achieved through creating device-mapper snapshots for each version When an AppVM is stopped the xen hotplug script checks whether the device is still in use – if it is not, the script removes the snapshot and frees the loop device. -### Changes to template filesystem +#### Changes to template filesystem In order for the full potential of the snapshot device to be realized, every change in root.img must save the original version of the modified block in root-cow.img. This is achieved by a snapshot-origin device. @@ -69,7 +71,7 @@ When TemplateVM is started, it receives the snapshot-origin device connected as When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.old and creates a new one (using the `qvm-template-commit` tool). The snapshot device will remain untouched due to the loop device, which uses an actual file on the disk (by inode, not by name). Linux kernel frees the old root-cow.img files as soon as they are unused by all snapshot devices (to be exact, loop devices). The new root-cow.img file will get a new inode number, and so new AppVMs will get new snapshot devices (with different names). -### Rollback template changes +#### Rollback template changes There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch". @@ -85,7 +87,7 @@ Steps performed by **qvm-revert-template-changes**: 6. Cleanup snapshot device (if nobody uses it at the moment). 7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). -## Snapshot device in AppVM +### Snapshot device in AppVM Root device is exposed to AppVM in read-only mode. AppVM can write only in: @@ -99,7 +101,7 @@ volatile.img is divided into two partitions: Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart. -## StandaloneVM +### StandaloneVM Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*. diff --git a/introduction/contributing.md b/introduction/contributing.md index 2ffb4699..c00359da 100644 --- a/introduction/contributing.md +++ b/introduction/contributing.md @@ -48,10 +48,10 @@ 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) -* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22) +* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows-tools%22) * [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22) * [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20) -* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22) +* [Debian/Ubuntu](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%2FUbuntu%22) 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, diff --git a/introduction/faq.md b/introduction/faq.md index b997cee0..5b334e91 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -186,10 +186,7 @@ We believe that this is currently the only practically viable approach to implem ### Does Qubes use full disk encryption (FDE)? -Yes, of course! -Full disk encryption is enabled by default. -Specifically, we use [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt). -You can even [manually configure your encryption parameters](/doc/custom-install/) if you like! +By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) to encrypt everything except the `/boot` partition. ### What do all these terms mean? @@ -331,6 +328,16 @@ So, if feature X isn't enabled, it's most likely for one of three reasons: If it seems like a feature that we can and should enable, please [let us know](/doc/issue-tracking/)! +### Why do the mailing lists require a Google account? + +They don't. This is a common misconception. The mailing lists have never required a Google account. It has always been possible to use them purely via email (see the [mailing lists](/support/#mailing-lists) section for instructions). + +A lot of people probably see that the mailing lists use Google Groups and just assume that a Google account must be required, but it's not true. Google Groups is simply used for the infrastructure. Of course, you *can* use the web interface with a Google account, but there are many people in the Qubes community who participate on the mailing lists without one. + +### Why do you use Google Groups for the mailing lists? + +For the same general reasons as listed in [FAQ: Why do you use GitHub?](/faq/#why-do-you-use-github) + ## Users ### Can I watch YouTube videos in qubes? @@ -787,7 +794,7 @@ UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very Arguably secure boot reliance on UEFI integrity is not the best design. The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested. Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS. -See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes. +See the Heads project [[1]](https://trmm.net/Heads) [[2]](https://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes. ### What is the canonical way to detect Qubes VM? diff --git a/introduction/issue-tracking.md b/introduction/issue-tracking.md index 58cbffbe..3e0975d7 100644 --- a/introduction/issue-tracking.md +++ b/introduction/issue-tracking.md @@ -16,11 +16,7 @@ ref: 121 title: Issue tracking --- -We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue -tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All -issues pertaining to the Qubes OS Project (including auxiliary infrastructure -such as this website) are tracked in -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues). +We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as this website) are tracked in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues). ## How to open a new issue @@ -28,306 +24,155 @@ First, let's make sure the issue tracker is the right place. ### I need help, have a question, or want to discuss something. -We're happy to help, answer questions, and have discussions, but the issue -tracker is not the right place for these activities. Instead, please see [Help, -Support, Mailing Lists, and Forum](/support/). +We're happy to help, answer questions, and have discussions, but the issue tracker is not the right place for these activities. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/). ### I see something that should be changed in the documentation. -We encourage you to submit the change yourself! Please see the [how to edit the -documentation](/doc/how-to-edit-the-documentation/) for instructions on how to -do so. If it's something you can't do yourself, please proceed to open an issue. +We encourage you to submit the change yourself! Please see the [how to edit the documentation](/doc/how-to-edit-the-documentation/) for instructions on how to do so. If it's something you can't do yourself, please proceed to open an issue. ### I would like to report a security vulnerability. -Thank you! If the vulnerability is confidential, please do not report it in our -public issue tracker. Instead, please see [Reporting Security Issues in Qubes -OS](/security/#reporting-security-issues-in-qubes-os). +Thank you! If the vulnerability is confidential, please do not report it in our public issue tracker. Instead, please see [Reporting Security Issues in Qubes OS](/security/#reporting-security-issues-in-qubes-os). ### I still want to open an issue. -Great! Thank you for taking the time and effort to help improve Qubes! To -ensure the process is efficient and productive for everyone involved, please -follow these steps: +Great! Thank you for taking the time and effort to help improve Qubes! To ensure the process is efficient and productive for everyone involved, please follow these steps: - 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. + 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'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. + 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'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. 9. Submit your issue. -10. Respond to any questions the official team asks. For example, you may be - asked to provide specific logs or other additional information. +10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information. -Eventually, your issue may be closed. See [how issues get -closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, -why, and how this occurs. +Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs. ## Labels, milestones, and projects -Labels, milestones, and projects are features of GitHub's issue tracking system -that we use to keep -[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. +Labels, milestones, and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized. ### Labels -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. +When an issue is first created, certain labels may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, 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`. +There are three issue **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. +- `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`. +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 problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `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. See [here](/doc/version-scheme/#bug-priorities) for details about how -the developers use these priorities. +There are several issue **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. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities. #### 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`. +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`. + +#### Affected release + +A label of the form `affects-` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases. ### 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. +The issue tracker has several [milestones](https://github.com/QubesOS/qubes-issues/milestones). Individual issues can be assigned to milestones. The issue tracker does not allow an issue to be assigned 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. Each milestone has a progress indicator showing how close that milestone is to completion. -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 `Release 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 `Non-release` 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. +Most milestones correspond to specific Qubes OS releases. The Qubes developers decide which issues will be assigned to specific milestones. The general idea is that each milestone's progress indicator should provide a rough idea of how much progress has been made on that milestone and how much work remains until the milestone is complete. Most issues will not be assigned to any milestone at all until a Qubes developer manually assigns it to one. While anyone is free to open an issue, this does not create an obligation on the Qubes developers to act on that issue. Every open issue should be understood to be merely "under consideration" unless or until a Qubes developer decides to assign it to a milestone. Issues that are assigned to a milestone are issues that either the Qubes developers or another contributor plans to complete *for* that milestone. The Qubes developers reserve the right to modify or remove milestones at any time at their discretion. ### 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. +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 -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.). -You can also try searching by -[milestone](https://github.com/QubesOS/qubes-issues/milestones) and by -[project](https://github.com/QubesOS/qubes-issues/projects). +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 -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. +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. +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/how-to-use-the-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/how-to-use-the-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](https://github.com/QubesOS/qubes-issues/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](https://github.com/QubesOS/qubes-issues/issues). -The Qubes team has its own roadmap and priorities, which will govern the manner -and order in which open issues are addressed. +Keep in mind that [qubes-issues](https://github.com/QubesOS/qubes-issues/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](https://github.com/QubesOS/qubes-issues/issues). The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed. + +### Issues and comments must be written in English + +If English is not your native language, you may post a machine translation. If you wish, you may also include the original non-English text in a [collapsible section](#use-collapsible-sections-for-long-nonessential-content). + +### Use collapsible sections for long, nonessential content + +On GitHub, create collapsible sections in Markdown like so: + +``` +
+Summary goes here. This line is optional. + +Long, nonessential content goes here. You can put a code block here, but make sure to leave empty lines before and after the fence lines (```). + +
+``` + +**Tip:** Use the "Preview" tab to make sure it renders correctly before posting. ## How issues get closed -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). +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 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 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 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. ### 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 the reported bug was fixed or the requested enhancement was implemented. +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 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: +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) @@ -337,20 +182,12 @@ affect multiple versions of Qubes OS, there are several possible states: 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)). +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. +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. +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. + +### Understanding open and closed issues + +Every issue is always in one of two states: open or closed, with open being the default. The **open** and **closed** states mean that, according to our available information at present, the issue in question either **is** or **is not** (respectively) actionable for the Qubes team. The open and closed states do not mean anything more than this, and it's important not to read anything else into them. It's also important to understand that closing an issue is, in effect, nothing more than changing a virtual tag on an issue. Closing an issue is never "final" in any sense, and it does not affect the issue itself in any other way. Issues can be opened and closed instantly with a single button press an unlimited number of times at no cost. In fact, since the open and closed states reflect our available information at present, one should expect these states to change back and forth as new information becomes available. Closed issues are fully searchable, just like open issues, and we explicitly instruct all users of the issue tracker to search *both* open *and* closed issues, which GitHub makes easy. diff --git a/introduction/support.md b/introduction/support.md index 842e3874..6f495938 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -512,6 +512,11 @@ on the [news](/news/) page. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news. +## Chat + +If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix +bridge: `#qubes:libera.chat`). + ## Unofficial venues If you find another venue on the Internet that is not listed above, it is @@ -522,9 +527,3 @@ moderate it. Please be especially careful in unofficial venues. should not be taken as a commitment to monitor or moderate the venue. It still remains unofficial. Also, please make sure someone claiming to be a Qubes team member really is one. It could be an impostor!) - -For example, here are some **unofficial** chat channels we know about that are -maintained by the community: - -* Matrix, Qubes-related: -* `#qubes` channel on irc.libera.chat via traditional IRC clients diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index faa27ea7..9a2df42c 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -294,11 +294,9 @@ Before we proceed, you must first complete the following prerequisite steps: 2. [Import and authenticate the QMSK.](#how-to-import-and-authenticate-the-qubes-master-signing-key) After you have completed these two prerequisite steps, the next step is to -obtain the correct RSK. The filename of the RSK for your Qubes OS release is -usually `qubes-release-X-signing-key.asc`, where `X` is the [major version -number](https://semver.org/) of your Qubes release. For example, if you were -installing release `1.2.3`, you would replace `X` with `1`, resulting in -`qubes-release-1-signing-key.asc`. There are several ways to get the RSK for +obtain the correct RSK. The filename pattern for RSKs is +`qubes-release-X-signing-key.asc`, where `X` is either a major or minor Qubes +release number, such as `4` or `4.2`. There are several ways to get the RSK for your Qubes release. - If you have access to an existing Qubes installation, the release keys are diff --git a/user/advanced-topics/awesomewm.md b/user/advanced-topics/awesomewm.md index 28f969da..96b6ba53 100644 --- a/user/advanced-topics/awesomewm.md +++ b/user/advanced-topics/awesomewm.md @@ -36,156 +36,3 @@ $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome For build instructions please check the repository _README_. The repository attempts to follow the upstream Fedora repository. - -## Common customizations - -This section focuses on Qubes-specific customizations. For generic AwesomeWM customizations you might want to have a look at the [AwesomeWM website](https://awesomewm.org). - -Customizations for AwesomeWM are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`. - -### Application menu - -Starting from Qubes 4.0 application menu entries specific to AwesomeWM can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created. - -### Focus steal hardening - -The default Qubes OS AwesomeWM installation comes with the defaults set by the AwesomeWM developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube. - -#### Definition - -For the below example we'll define _wanted focus changes_ as one of the below: - -* mouse move & click afterwards -* workspace/tag change -* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k) -* tag assignments and unassignments - -Everything else is considered an unwanted _focus steal_. - -In particular the following events are not meant to cause a focus change: - -* new window created -* a window was closed -* application request -* mouse move without click (sloppy focus) - -For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.: - -* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window) -* windows shouldn't be able to change their size themselves -* windows shouldn't be able to modify their borders in any way - -Users may want to adjust their definitions and respective implementations according to their needs. - -#### Implementation - -The implementation may be specific to the AwesomeWM version you're running. This guide refers to AwesomeWM version 3.5.9 which is available to Qubes 4.0 users. - -Please keep in mind that this guide may not be conclusive. Your mileage may vary. - -##### Change the autofocus implementation - -The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your AwesomeWM instance. - -In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`. - -Then you can customise the focus behavior. According to our above definitions it would look as follows: - -```lua ----autofocus_custom.lua -local client = client -local screen = screen -local aclient = require("awful.client") -local atag = require("awful.tag") - ---- When loaded, this module makes sure that there's always a client that will have focus --- on events such as tag switching, client unmanaging, etc. --- awful.autofocus - --- Give focus when clients appear/disappear and no one else has focus. --- @param obj An object that should have a .screen property. -function check_focus(obj) - -- When no visible client has the focus... - if not client.focus or not client.focus:isvisible() then - local c = aclient.focus.history.get(obj.screen, 0) - if c then client.focus = c end - end -end - --- Give focus on tag selection change. --- @param tag A tag object -function check_focus_tag(t) - local s = atag.getscreen(t) - if not s then return end - check_focus({ screen = s }) - if client.focus and client.focus.screen ~= s then - local c = aclient.focus.history.get(s, 0) - if c then client.focus = c end - end -end - ---made above functions global & removed some focus switches below (user interaction required instead) - ---clear any focus -function clear_focus() - --unfortunately this doesn't work at the moment - --cf. https://github.com/awesomeWM/awesome/issues/164 - --(Qubes uses an older AwesomeWM version that doesn't have the fix yet) - --client.focus = nil -end - -atag.attached_connect_signal(nil, "property::selected", check_focus_tag) -client.connect_signal("unmanage", clear_focus) -client.connect_signal("tagged", check_focus) -client.connect_signal("untagged", check_focus) -client.connect_signal("property::hidden", clear_focus) -client.connect_signal("property::minimized", clear_focus) -``` - -##### Remove unwanted focus changing key bindings - -The mouse bindings - -```lua -awful.button({ }, 4, awful.tag.viewnext), -awful.button({ }, 5, awful.tag.viewprev) -``` - -in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out. - -##### Adjust client rules - -The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`. - -Alternatively users may provide their own focus filter functions. - -##### Disable sloppy focus - -In your _rc.lua_ you'll find a section such as - -```lua - -- Enable sloppy focus - c:connect_signal("mouse::enter", function(c) - if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier - and awful.client.focus.filter(c) then - client.focus = c - end - end) -``` - -These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour. - -##### Ignore requests from applications to the window manager - -Handling of such requests is currently mostly implemented by AwesomeWM in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each AwesomeWM update though) or disconnect the signals in your _rc.lua_. - -As of AwesomeWM 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_: - -```lua -local ewmh = require("awful.ewmh") - -client.disconnect_signal("request::activate", ewmh.activate) -client.disconnect_signal("request::tag", ewmh.tag) -``` - -The signal names may change across AwesomeWM versions. diff --git a/user/advanced-topics/disposable-customization.md b/user/advanced-topics/disposable-customization.md index bb34cd98..86186de4 100644 --- a/user/advanced-topics/disposable-customization.md +++ b/user/advanced-topics/disposable-customization.md @@ -15,62 +15,54 @@ title: Disposable customization ## Introduction -A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube). -You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables. -To prepare an app qube to be a disposable template, you need to set `template_for_dispvms` property, for example: +A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube). You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables. To prepare an app qube to be a disposable template, you need to set the `template_for_dispvms` property: ```shell_session -[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True +[user@dom0 ~]$ qvm-prefs template_for_dispvms True ``` -Additionally, if you want to have menu entries for starting applications in disposable based on this app qube (instead of in the app qube itself), you can achieve it with `appmenus-dispvm` feature: +Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the `appmenus-dispvm` feature: ```shell_session -[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1 +[user@dom0 ~]$ qvm-features appmenus-dispvm 1 ``` -Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information. +**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information. ## Security -If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised. -Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates. -In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. -This means that it will have access to everything that you open with this feature. -For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it. +If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised. Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates. In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it. ## Creating a new disposable template -In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. -To create new disposable template, lets say `custom-disposable-template`, based on `debian-9` template, use following commands: +In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template: ```shell_session -[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposable-template -[user@dom0 ~]$ qvm-prefs custom-disposable-template template_for_dispvms True -[user@dom0 ~]$ qvm-features custom-disposable-template appmenus-dispvm 1 +[user@dom0 ~]$ qvm-create --template