diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb3c2a96b..ede0d1236 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,8 @@ -Contributing to `qubes-doc` -=========================== +# Contributing to `qubes-doc` Thank you for your interest in contributing to `qubes-doc`, the Qubes OS Project's dedicated documentation repository! Please take a moment to read our -[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before you begin writing. These guidelines are -important to maintaining high quality documentation, and following them will -increase the likelihood that your contribution will be accepted. - +[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before +you begin writing. These guidelines are important to maintaining high quality +documentation, and following them will increase the likelihood that your +contribution will be accepted. diff --git a/README.md b/README.md index 48fcaba8e..c31a58ee0 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@ -Qubes OS Documentation -====================== +# Qubes OS Documentation Canonical URL: https://www.qubes-os.org/doc/ -All [Qubes OS Project](https://github.com/QubesOS) documentation pages are stored as plain text -files in this dedicated 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. +All [Qubes OS Project](https://github.com/QubesOS) documentation pages are +stored as plain text files in this dedicated 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. For more information about the documentation, including how to contribute, please see the [Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/). - diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 53646679f..ecfc20304 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -10,7 +10,6 @@ ref: 66 title: Development Workflow --- - A workflow for developing Qubes OS+ First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide @@ -537,4 +536,3 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and ~~~ deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main ~~~ - diff --git a/developer/building/qubes-builder-details.md b/developer/building/qubes-builder-details.md index d6fdb259a..8b5c8c8a8 100644 --- a/developer/building/qubes-builder-details.md +++ b/developer/building/qubes-builder-details.md @@ -10,7 +10,6 @@ ref: 65 title: Qubes Builder Details --- - Components Makefile.builder file -------------------------------- diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index 0455e6e6d..f30b7b26f 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -12,7 +12,6 @@ ref: 63 title: Qubes ISO Building --- - Build Environment ----------------- diff --git a/developer/building/qubes-template-configs.md b/developer/building/qubes-template-configs.md index 7c97b775f..446fa39fb 100644 --- a/developer/building/qubes-template-configs.md +++ b/developer/building/qubes-template-configs.md @@ -3,5 +3,6 @@ lang: en layout: doc permalink: /doc/qubes-template-configs/ redirect_to: https://github.com/QubesOS/qubes-template-configs +ref: 248 title: Qubes Template Configs --- diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index 09492c2b9..236c6aac4 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -6,7 +6,6 @@ ref: 51 title: Code Signing --- - All contributions to the Qubes OS [source code](/doc/source-code/) must be cryptographically signed by the author's PGP key. ## Generating a Key @@ -202,4 +201,3 @@ Please upload it. If you're submitting a patch by emailing the [developer mailing list](/support/#qubes-devel), simply sign your email with your PGP key. One good way to do this is with a program like [Enigmail](https://www.enigmail.net/). Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails. - diff --git a/developer/code/coding-style.md b/developer/code/coding-style.md index ac7fdf23b..4f2013c59 100644 --- a/developer/code/coding-style.md +++ b/developer/code/coding-style.md @@ -11,7 +11,6 @@ ref: 53 title: Coding Style --- - Rationale --------- diff --git a/developer/code/license.md b/developer/code/license.md index 91325bf42..95d71c233 100644 --- a/developer/code/license.md +++ b/developer/code/license.md @@ -10,7 +10,14 @@ ref: 52 title: Software License --- +Qubes OS is a compilation of software packages, each under its own license. The +compilation is made available under the GNU General Public License version 2 +(GPLv2). -Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2. +The source code of Qubes OS is contained in repositories under the +[@QubesOS](https://github.com/QubesOS) account on GitHub. This source code is +made available under GPLv2, unless there is a `LICENSE` file in the root of the +containing repository that specifies a different license. -The full text of the GPL v2 license can be found [here](https://www.gnu.org/licenses/gpl-2.0.html). +The full text of the GPLv2 license can be found +[here](https://www.gnu.org/licenses/gpl-2.0.html). diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 05ee47d07..7098ace7f 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -10,7 +10,6 @@ ref: 54 title: Source Code --- - All the Qubes code is kept in Git repositories. We have divided the project into several components, each of which has its own separate repository, for example: @@ -81,4 +80,3 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b name and email, so that *your* name will be used as a commit's author. 5. Send your patch to `qubes-devel`. Start the message subject with `[PATCH]`. - diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index ab69aa623..e4a7e6747 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -9,7 +9,6 @@ ref: 45 title: Automated Tests --- - ## Unit and Integration Tests Starting with Qubes R3 we use [python unittest](https://docs.python.org/3/library/unittest.html) to perform automatic tests of Qubes OS. @@ -114,7 +113,7 @@ vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file Example test run: -![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png) +![snapshot-tests2.png](/attachment/doc/snapshot-tests2.png) Tests are also compatible with nose2 test runner, so you can use this instead: @@ -260,4 +259,3 @@ In practice, however, either Xen or QEMU crashes when this is attempted. Nonetheless, PV works well, which is sufficient for automated installation testing. Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements. - diff --git a/developer/debugging/mount-lvm-image.md b/developer/debugging/mount-lvm-image.md index 745975780..d484b5a73 100644 --- a/developer/debugging/mount-lvm-image.md +++ b/developer/debugging/mount-lvm-image.md @@ -6,7 +6,6 @@ ref: 46 title: How to Mount LVM Images --- - You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0). 1: make the image available for qubesdb. @@ -53,4 +52,3 @@ From the GUI, or from the command line: # References Please consult this issue's [comment](https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625). - diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md index 0724f4b99..230351de7 100644 --- a/developer/debugging/profiling.md +++ b/developer/debugging/profiling.md @@ -10,7 +10,6 @@ ref: 48 title: Python Profiling --- - This is a python profiling primer. For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats. @@ -94,6 +93,6 @@ make REMOTE=example.com:public_html/qubes/profiling/ upload This example is from `qubes-manager` (`qubesmanager/main.py`). -!["update\_table-20140424-170010.svg"](//attachment/wiki/Profiling/update_table-20140424-170010.svg) +!["update\_table-20140424-170010.svg"](//attachment/doc/update_table-20140424-170010.svg) It is apparent that the problem is around `get_disk_usage`, which calls something via `subprocess.call`. It does this 15 times, probably once per VM. diff --git a/developer/debugging/safe-remote-ttys.md b/developer/debugging/safe-remote-ttys.md index 89286b7f5..bd71d96c4 100644 --- a/developer/debugging/safe-remote-ttys.md +++ b/developer/debugging/safe-remote-ttys.md @@ -8,7 +8,6 @@ ref: 49 title: Safe Remote Dom0 Terminals --- - If you do not have working graphics in Dom0, then using a terminal can be quite annoying! This was the case for the author while trying to debug PCI-passthrough of a machine's primary (only) GPU. diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md index bc21ea3fd..5ec3fee57 100644 --- a/developer/debugging/test-bench.md +++ b/developer/debugging/test-bench.md @@ -10,62 +10,75 @@ ref: 44 title: How to Set Up a Test Bench --- - This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal. We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly. -## Setting up the machine +> **Notice:** +> This setup intentionally weakens some security properties in the testing system. So make sure you understand the risks and use exclusively for testing. -First, do a clean install from ISO you built or grabbed elsewhere. +## Setting up the Machine -You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else. +### Install ISO +First, do a clean install from the `.iso` [you built](/doc/qubes-iso-building/) or grabbed elsewhere (for example [here](https://qubes-os.discourse.group/t/qubesos-4-1-alpha-signed-weekly-builds/3601)) -```bash -#!/bin/sh +### Enabling Network Access in Dom0 -# adjust this for your NIC (run lspci) -BDF=0000:02:00.0 - -prog=$(basename $0) - -pciunbind() { - local path - path=/sys/bus/pci/devices/${1}/driver/unbind - if ! [ -w ${path} ]; then - echo "${prog}: Device ${1} not bound" - return 1 - fi - echo -n ${1} >${path} -} - -pcibind() { - local path - path=/sys/bus/pci/drivers/${2}/bind - if ! [ -w ${path} ]; then - echo "${prog}: Driver ${2} not found" - return 1 - fi - echo ${1} >${path} -} - -pciunbind ${BDF} -pcibind ${BDF} e1000e - -dhclient -``` +Internet access is intentionally disabled by default in dom0. But to ease the deployment process we will give it access. The following steps should be done in `dom0`. -TODO: describe how to run this at every startup +> **Note:** the following assume you have only one network card. If you have two, pick one and leave the other attached to `sys-net`. -Now configure your DHCP server so your testbench gets static IP and connect your machine to your local network. You should ensure that your testbench can reach the Internet. +1. Remove the network card (PCI device) from `sys-net` +2. Restart your computer (for the removal to take effect) +3. The following script should enable your network card in dom0. *Be sure to adjust the script's variables to suit your needs.* You'll need to run this at every startup (TODO: describe how to run this at every startup). -Install `openssh-server` on your testbench: + ```bash + #!/bin/sh -~~~ -yum install openssh-server -~~~ + # adjust this for your NIC (run lspci) + BDF=0000:02:00.0 + + # adjust this for your network driver + DRIVER=e1000e -Ensure that sudo works without password from your user account (it should by default). + prog=$(basename $0) + + pciunbind() { + local path + path=/sys/bus/pci/devices/${1}/driver/unbind + if ! [ -w ${path} ]; then + echo "${prog}: Device ${1} not bound" + return 1 + fi + echo -n ${1} >${path} + } + + pcibind() { + local path + path=/sys/bus/pci/drivers/${2}/bind + if ! [ -w ${path} ]; then + echo "${prog}: Driver ${2} not found" + return 1 + fi + echo ${1} >${path} + } + + pciunbind ${BDF} + pcibind ${BDF} ${DRIVER} + + sleep 1 + dhclient + ``` + +4. Configure your DHCP server so your testbench gets static IP and connect your machine to your local network. You should ensure that your testbench can reach the Internet. + +5. Install `openssh-server` on your testbench. + + ~~~ + sudo dnf --setopt=reposdir=/etc/yum.repos.d install openssh-server + ~~~ + +> **Note:** If you want to install additional software in dom0 and your only network card was assigned to dom0, then _instead_ of the usual `sudo qubes-dom0-update ` now you run `sudo dnf --setopt=reposdir=/etc/yum.repos.d install `. ## Development VM @@ -87,7 +100,9 @@ Host testbench HostName 192.168.123.45 ~~~ -Then connect to your testbench and paste newly generated `id_ecdsa.pub` to `.ssh/authorized_keys` on testbench so you can log in without entering password every time. +#### Passwordless SSH Login + +To log to your testbench without entering password every time, copy your newly generated public key (`id_ecdsa.pub`) to `~/.ssh/authorized_keys` on your testbench. You can do this easily by running this command on `qubes-dev`: `ssh-copy-id -i ~/.ssh/id_ecdsa.pub user@192.168.123.45` (substituting with the actual username address of your testbench). ### Scripting @@ -116,7 +131,7 @@ fi set -e ssh testbench mkdir -p "${TMPDIR}" -scp "${@}" testbench:"${TMPDIR}" +scp "${@}" testbench:"${TMPDIR}" || echo "check if you have 'scp' installed on your testbench" while [ $# -gt 0 ]; do ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})" diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index 5d7e64921..741e52c78 100644 --- a/developer/debugging/vm-interface.md +++ b/developer/debugging/vm-interface.md @@ -11,7 +11,6 @@ ref: 47 title: VM Configuration Interface --- - Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: - QubesDB diff --git a/developer/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md index 8ab71f110..cc81c2c44 100644 --- a/developer/debugging/windows-debugging.md +++ b/developer/debugging/windows-debugging.md @@ -10,7 +10,6 @@ ref: 50 title: Windows Debugging --- - Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs. User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM. diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index abadd2b6e..628a7b99f 100644 --- a/developer/general/doc-guidelines.md +++ b/developer/general/doc-guidelines.md @@ -10,190 +10,283 @@ ref: 30 title: Documentation Guidelines --- +All Qubes OS documentation pages are stored as plain text files in the +dedicated [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. -All Qubes OS documentation pages are stored as plain text files in the dedicated [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 community effort. Volunteers work hard trying to keep everything accurate and comprehensive. -If you notice a problem or some way it can be improved, please [edit the documentation](#how-to-contribute)! +The documentation is a community effort. Volunteers work hard trying to keep +everything accurate and comprehensive. If you notice a problem or some way it +can be improved, please [edit the documentation](#how-to-contribute)! ## Security *Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)* -All pull requests (PRs) against [qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be merged, except in the case of [external documentation](/doc/#external-documentation) (see [#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). -This process is designed to ensure that contributed text is accurate and non-malicious. -This process is a best effort that should provide a reasonable degree of assurance, but it is not foolproof. -For example, all text characters are checked for ANSI escape sequences. -However, binaries, such as images, are simply checked to ensure they appear or function the way they should when the website is rendered. -They are not further analyzed in an attempt to determine whether they are malicious. - -Once a pull request passes review, the reviewer should add a signed comment stating, "Passed review as of ``" (or similar). -The documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.). -If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote. -In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag). +All pull requests (PRs) against +[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be +merged, except in the case of [external +documentation](/doc/#external-documentation) (see +[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is +designed to ensure that contributed text is accurate and non-malicious. This +process is a best effort that should provide a reasonable degree of assurance, +but it is not foolproof. For example, all text characters are checked for ANSI +escape sequences. However, binaries, such as images, are simply checked to +ensure they appear or function the way they should when the website is +rendered. They are not further analyzed in an attempt to determine whether they +are malicious. + +Once a pull request passes review, the reviewer should add a signed comment +stating, "Passed review as of ``" (or similar). The +documentation maintainer then verifies that the pull request is mechanically +sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the +documentation maintainer then merges the pull request, adds a PGP-signed tag to +the latest commit (usually the merge commit), then pushes to the remote. In +cases in which another reviewer is not required, the documentation maintainer +may review the pull request (in which case no signed comment is necessary, +since it would be redundant with the signed tag). ## Questions, problems, and improvements -If you have a question about something you read in the documentation, please send it to the appropriate [mailing list](/support/). -If you see that something in the documentation should be fixed or improved, please [contribute](#how-to-contribute) the change yourself. -To report an issue with the documentation, please follow our standard [issue reporting guidelines](/doc/reporting-bugs/). -(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.) +If you have a question about something you read in the documentation, please +send it to the appropriate [mailing list](/support/). If you see that something +in the documentation should be fixed or improved, please +[contribute](#how-to-contribute) the change yourself. To report an issue with +the documentation, please follow our standard [issue reporting +guidelines](/doc/issue-tracking/). (If you report an issue with the +documentation, you will likely be asked to address it, unless there is a clear +indication in your report that you are not willing or able to do so.) ## How to contribute -Editing the documentation is easy, so if you see that a change should be made, please contribute it! +Editing the documentation is easy, so if you see that a change should be made, +please contribute it! A few notes before we get started: -* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted. - This allows us to maintain quality control and protect our users. -* We don't want you to spend time and effort on a contribution that we can't accept. - If your contribution would take a lot of time, please [file an issue](/doc/reporting-bugs/) for it first so that we can make sure we're on the same page before significant works begins. -* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does. - In this case, you can still submit it by following the instructions below. - Just make a note in your pull request (PR) that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes. - -As mentioned above, we keep all the documentation in a dedicated [Git repository](https://github.com/QubesOS/qubes-doc) hosted on [GitHub](https://github.com/). -Thanks to GitHub's interface, you can edit the documentation even if you don't know Git at all! -The only thing you need is a GitHub account, which is free. - -(**Note:** If you're already familiar with GitHub or wish to work from the command line, you can skip the rest of this section. -All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/).) - -Ok, let's start. -Every documentation page has an "Edit this page" button. -It may be on the side (in the desktop layout): - -[![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)](/attachment/wiki/doc-edit/03-button2.png) +* Since Qubes is a security-oriented project, every documentation change will + be reviewed before it's accepted. This allows us to maintain quality control + and protect our users. +* We don't want you to spend time and effort on a contribution that we can't + accept. If your contribution would take a lot of time, please [file an + issue](/doc/issue-tracking/) for it first so that we can make sure we're on + the same page before significant works begins. +* Alternatively, you may already have written content that doesn't conform to + these guidelines, but you'd be willing to modify it so that it does. In this + case, you can still submit it by following the instructions below. Just make + a note in your pull request (PR) that you're aware of the changes that need + to be made and that you're just asking for the content to be reviewed before + you spend time making those changes. + +As mentioned above, we keep all the documentation in a dedicated [Git +repository](https://github.com/QubesOS/qubes-doc) hosted on +[GitHub](https://github.com/). Thanks to GitHub's interface, you can edit the +documentation even if you don't know Git at all! The only thing you need is a +GitHub account, which is free. + +(**Note:** If you're already familiar with GitHub or wish to work from the +command line, you can skip the rest of this section. All you need to do to +contribute is to [fork and +clone](https://guides.github.com/activities/forking/) the +[qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then +[submit a pull +request](https://help.github.com/articles/using-pull-requests/).) + +Ok, let's start. Every documentation page has an "Edit this page" button. It +may be on the side (in the desktop layout): + +[![edit-button-desktop](/attachment/doc/03-button2.png)](/attachment/doc/03-button2.png) Or at the bottom (in the mobile layout): -[![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)](/attachment/wiki/doc-edit/02-button1.png) +[![edit-button-mobile](/attachment/doc/02-button1.png)](/attachment/doc/02-button1.png) -When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in). -You can also create an account from here. +When you click on it, you'll be prompted for your GitHub username and password +(if you aren't already logged in). You can also create an account from here. -[![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)](/attachment/wiki/doc-edit/04-sign-in.png) +[![github-sign-in](/attachment/doc/04-sign-in.png)](/attachment/doc/04-sign-in.png) -If this is your first contribution to the documentation, you need to "fork" the repository (make your own copy). It's easy --- just click the big green button on the next page. -This step is only needed the first time you make a contribution. +If this is your first contribution to the documentation, you need to "fork" the +repository (make your own copy). It's easy --- just click the big green button +on the next page. This step is only needed the first time you make a +contribution. -[![fork](/attachment/wiki/doc-edit/05-fork.png)](/attachment/wiki/doc-edit/05-fork.png) +[![fork](/attachment/doc/05-fork.png)](/attachment/doc/05-fork.png) -Now you can make your modifications. -You can also preview the changes to see how they'll be formatted by clicking the "Preview changes" tab. -If you want to add images, please see [How to add images](#how-to-add-images). -If you're making formatting changes, please [render the site locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify that everything looks correct before submitting any changes. +Now you can make your modifications. You can also preview the changes to see +how they'll be formatted by clicking the "Preview changes" tab. If you want to +add images, please see [How to add images](#how-to-add-images). If you're +making formatting changes, please [render the site +locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify +that everything looks correct before submitting any changes. -[![edit](/attachment/wiki/doc-edit/06-edit.png)](/attachment/wiki/doc-edit/06-edit.png) +[![edit](/attachment/doc/06-edit.png)](/attachment/doc/06-edit.png) -Once you're finished, describe your changes at the bottom and click "Propose file change". +Once you're finished, describe your changes at the bottom and click "Propose +file change". -[![commit](/attachment/wiki/doc-edit/07-commit-msg.png)](/attachment/wiki/doc-edit/07-commit-msg.png) +[![commit](/attachment/doc/07-commit-msg.png)](/attachment/doc/07-commit-msg.png) -After that, you'll see exactly what modifications you've made. -At this stage, those changes are still in your own copy of the documentation ("fork"). -If everything looks good, send those changes to us by pressing the "Create pull request" button. +After that, you'll see exactly what modifications you've made. At this stage, +those changes are still in your own copy of the documentation ("fork"). If +everything looks good, send those changes to us by pressing the "Create pull +request" button. -[![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)](/attachment/wiki/doc-edit/08-review-changes.png) +[![pull-request](/attachment/doc/08-review-changes.png)](/attachment/doc/08-review-changes.png) -You will be able to adjust the pull request message and title there. -In most cases, the defaults are ok, so you can just confirm by pressing the "Create pull request" button again. +You will be able to adjust the pull request message and title there. In most +cases, the defaults are ok, so you can just confirm by pressing the "Create +pull request" button again. -[![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)](/attachment/wiki/doc-edit/09-create-pull-request.png) +[![pull-request-confirm](/attachment/doc/09-create-pull-request.png)](/attachment/doc/09-create-pull-request.png) -If any of your changes should be reflected in the [documentation index (a.k.a. table of contents)](/doc/) --- for example, if you're adding a new page, changing the title of an existing page, or removing a page --- please see [How to edit the documentation index](#how-to-edit-the-documentation-index). +If any of your changes should be reflected in the [documentation index (a.k.a. +table of contents)](/doc/) --- for example, if you're adding a new page, +changing the title of an existing page, or removing a page --- please see [How +to edit the documentation index](#how-to-edit-the-documentation-index). -That's all! -We will review your changes. -If everything looks good, we'll pull them into the official documentation. -Otherwise, we may have some questions for you, which we'll post in a comment on your pull request. -(GitHub will automatically notify you if we do.) -If, for some reason, we can't accept your pull request, we'll post a comment explaining why we can't. +That's all! We will review your changes. If everything looks good, we'll pull +them into the official documentation. Otherwise, we may have some questions for +you, which we'll post in a comment on your pull request. (GitHub will +automatically notify you if we do.) If, for some reason, we can't accept your +pull request, we'll post a comment explaining why we can't. -[![done](/attachment/wiki/doc-edit/10-done.png)](/attachment/wiki/doc-edit/10-done.png) +[![done](/attachment/doc/10-done.png)](/attachment/doc/10-done.png) ## How to edit the documentation index -The source file for the [documentation index (a.k.a. table of contents)](/doc/) lives here: +The source file for the [documentation index (a.k.a. table of contents)](/doc/) +lives here: - + -Editing this file will change what appears on the documentation index. -If your pull request (PR) adds, removes, or edits anything that should be reflected in the documentation index, please make sure you also submit an associated pull request against this file. +Editing this file will change what appears on the documentation index. If your +pull request (PR) adds, removes, or edits anything that should be reflected in +the documentation index, please make sure you also submit an associated pull +request against this file. ## How to add images -To add an image to a page, use the following syntax in the main document. -This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself. +To add an image to a page, use the following syntax in the main document. This +will make the image a hyperlink to the image file, allowing the reader to click +on the image in order to view the image by itself. ``` -[![Image Title](/attachment/wiki/page-title/image-filename.png)](/attachment/wiki/page-title/image-filename.png) +[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png) ``` -Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename. -This is the only permitted way to include images. -Do not link to images on other websites. +Then, submit your image(s) in a separate pull request to the +[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository +using the same path and filename. This is the only permitted way to include +images. Do not link to images on other websites. ## 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](#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the "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. - -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 go through a review process to ensure accuracy before being merged (see [security](#security)), 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. - -See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more background information. +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](#how-to-edit-the-documentation-index)) to add +and update Qubes Community links in the "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. + +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 go through a review process to ensure +accuracy before being merged (see [security](#security)), 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. + +See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more +background information. ### Version-specific documentation -*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential changes to this policy.* +*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential +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 version 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 version 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 versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions: +In cases where a documentation page covers functionality that differs +considerably between Qubes OS versions, the page should be subdivided into +clearly-labeled sections that cover the different functionality in different +versions: #### Incorrect Example @@ -256,119 +349,215 @@ 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 version has several benefits: - -* It preserves good content for older (but still supported) versions. - Many documentation contributors are also people who prefer to use the latest version. - Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version. - This is somewhat understandable. - Since they only use the latest version, they may be focused on their own experience, and they may even regard the older version 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 version. - In many cases, these users value the stability and reliability of the older, supported version. - With the older, supported version, 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 version 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 version. -* 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 version-specific sections is not a problem, since no reader has to read the same thing twice. - Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated. - Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing: - We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version 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 versions. - 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 versions. - -By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions 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-version-specific content. -Good general content that was submitted only to one branch would effectively disappear once that version 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 version, 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 version-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). +Subdividing the page into clearly-labeled sections for each version has several +benefits: + +* It preserves good content for older (but still supported) versions. Many + documentation contributors are also people who prefer to use the latest + version. Many of them are tempted to *replace* existing content that applies + to an older, supported version with content that applies only to the latest + version. This is somewhat understandable. Since they only use the latest + version, they may be focused on their own experience, and they may even + regard the older version 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 version. In many + cases, these users value the stability and reliability of the older, + supported version. With the older, supported version, 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 + version 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 version. +* 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 version-specific sections is not a problem, since no reader has to read + the same thing twice. Moreover, as one version gets updated, it's likely that + the documentation for that version will also be updated. Therefore, content + that is initially duplicated between version-specific sections will not + necessarily stay that way, and this is a good thing: We want the + documentation for a version that *doesn't* change to stay the same, and we + want the documentation for a version 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 versions. + 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 + versions. + +By contrast, an alternative approach, such as segregating the documentation +into two different branches, would mean that contributions that apply to both +Qubes versions 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-version-specific content. Good general content +that was submitted only to one branch would effectively disappear once that +version 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 +version, 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 version-specific documentation in Qubes, see +[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion). ## Style guidelines -* Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). Use these - terms consistently and accurately throughout your writing. - * Syntactically distinguish variables in commands. - For example, this is ambiguous: +* Familiarize yourself with the terms defined in the + [glossary](/doc/glossary/). Use these terms consistently and accurately + throughout your writing. +* Syntactically distinguish variables in commands. For example, this is + ambiguous: - $ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm + $ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm - It should instead be: + It should instead be: - $ qvm-run --dispvm= --service qubes.StartApp+xterm + $ qvm-run --dispvm= --service qubes.StartApp+xterm - Note that we syntactically distinguish variables in three ways: - 1. Surrounding them in angled brackets (`< >`) - 2. Using underscores (`_`) between words - 3. Using all capital letters + Note that we syntactically distinguish variables in three ways: + 1. Surrounding them in angled brackets (`< >`) + 2. Using underscores (`_`) between words + 3. Using all capital letters ## Markdown conventions -All the documentation is written in Markdown for maximum accessibility. -When making contributions, please try to observe the following style conventions: - - * Use spaces instead of tabs. - * 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. - * Link only to images in [qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see [instructions above](#how-to-add-images)). - Do not link to images on other websites. - * In order to enable offline browsing and automatic onion redirection, always use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`. - Examples of exceptions: - * The signed plain text portions of [QSBs](/security/bulletins/) and [Canaries](/security/canaries/) - * URLs that appear inside code blocks (e.g., in comments and document templates) - * Files like `README.md` and `CONTRIBUTING.md` - * Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples). - * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. - It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. -* If appropriate, make numerals in numbered lists match between Markdown source and HTML output. - * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. -* Use hanging indentations - where appropriate. -* Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML frontmatter. +All the documentation is written in Markdown for maximum accessibility. When +making contributions, please try to observe the following style conventions: + +* Use spaces instead of tabs. +* 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. +* Link only to images in + [qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see + [instructions above](#how-to-add-images)). Do not link to images on other + websites. +* In order to enable offline browsing and automatic onion redirection, always + use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/` + instead of `https://www.qubes-os.org/doc/doc-guidelines/`. Examples of + exceptions: + * The signed plain text portions of [QSBs](/security/qsb/) and + [Canaries](/security/canary/) + * URLs that appear inside code blocks (e.g., in comments and document + templates) + * Files like `README.md` and `CONTRIBUTING.md` +* Hard wrap Markdown lines at 80 characters, unless the line can't be broken + (e.g., code or a URL). +* If appropriate, make numerals in numbered lists match between Markdown source + and HTML output. + * Rationale: In the event that a user is required to read the Markdown source + directly, this will make it easier to follow, e.g., numbered steps in a set + of instructions. +* Use hanging indentations where appropriate. +* Do not use `h1` headings (single `#` or `======` underline). These are + automatically generated from the `title:` line in the YAML frontmatter. * Use Atx-style headings: , `##h 2`, `### h3`, etc. -* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted. +* When writing code blocks, use [syntax + highlighting](https://github.github.com/gfm/#info-string) where + [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) + and use `[...]` for anything omitted. * 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.: - - ~~~markdown - Open a terminal in dom0 and run: - ```shell_session - $ cd test - $ echo Hello - Hello - ``` - ~~~ - - * 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: - - ~~~markdown - Open a terminal in dom0 and run: - ```shell_session - # Navigate to the new directory - $ cd test - # Generate a greeting - $ echo Hello - Hello - ``` - ~~~ - - The `#` symbol preceding each comment is ambiguous with a root command prompt. - Instead, put your comments *outside* of the code block in normal prose. -* Use non-reference-style links like `[website](https://example.com/)`. - Do *not* use reference links like `[website][example]`, `[website][]` or `[website]`. - -([This](https://daringfireball.net/projects/markdown/) is a great source for learning about Markdown.) + * 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: + ```shell_session + $ cd test + $ echo Hello + Hello + ``` + ~~~ + + * 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: + + ~~~markdown + Open a terminal in dom0 and run: + ```shell_session + # Navigate to the new directory + $ cd test + # Generate a greeting + $ echo Hello + Hello + ``` + ~~~ + + The `#` symbol preceding each comment is ambiguous with a root command + prompt. Instead, put your comments *outside* of the code block in normal + prose. +* Use non-reference-style links like `[website](https://example.com/)`. Do + *not* use reference links like `[website][example]`, `[website][]` or + `[website]`. + +([This](https://daringfireball.net/projects/markdown/) is a great source for +learning about Markdown.) + +## Coding conventions + +These conventions apply to the website as a whole, including everything written +in HTML, CSS, YAML, and Liquid. These conventions are intended to keep the +codebase consistent when multiple collaborators are working on it. They should +be understood as a practical set of rules for maintaining order in this +specific codebase rather than as a statement of what is objectively right or +good. + +* Always use spaces. Never use tabs. +* Indent by exactly two (2) spaces. +* Whenever you add an opening tag, indent the following line. (Exception: If + you open and close the tag on the same line, do not indent the following + line.) +* Indent Liquid the same way as HTML. +* In general, the starting columns of every adjacent pair of lines should be no + more than two spaces apart (example below). +* No blank or empty lines. (Hint: When you feel you need one, add a comment on + that line instead.) +* Use comments to indicate the purposes of different blocks of code. This makes + the file easier to understand and navigate. +* Use descriptive variable names. Never use one or two letter variable names. + Avoid uncommon abbreviations and made-up words. +* In general, make it easy for others to read your code. Your future self will + thank you, and so will your collaborators! +* [Don't Repeat Yourself + (DRY)!](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) Instead of + repeating the same block of code multiple times, abstract it out into a + separate file and `include` that file where you need it. + +### Indentation example + +Here's an example that follows the indentation rules: + +{% raw %} +```html + + + + {% for item in secs.htmlsections[0].columns %} + + {% endfor %} + + {% for canary in site.data.sec-canary reversed %} + + + + + + {% endfor %} +
{{ item.title }}
{{ canary.date }}Qubes Canary #{{ canary.canary }}
+``` +{% endraw %} ## Git conventions -Please try to write good commit messages, according to the -[instructions in our coding style guidelines](/doc/coding-style/#commit-message-guidelines). - +Please try to write good commit messages, according to the [instructions in our +coding style guidelines](/doc/coding-style/#commit-message-guidelines). diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index c007b52cc..c99e5580c 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -1,6 +1,6 @@ --- lang: en -layout: sidebar +layout: doc permalink: /gsoc/ redirect_from: - /GSoC/ @@ -586,4 +586,3 @@ would override all the user changes there). More details: ---- We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC). - diff --git a/developer/general/gsod.md b/developer/general/gsod.md index b8b4c7d86..76e40c76e 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -1,12 +1,11 @@ --- lang: en -layout: sidebar +layout: doc permalink: /gsod/ ref: 242 title: Google Season of Docs --- - 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). ## 2021 Project Idea @@ -111,7 +110,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/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](https://www.qubes-os.org/doc/how-to-get-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**: @@ -145,4 +144,3 @@ Fixing this last point may require very close cooperation with developers, as th - [Markdown](https://daringfireball.net/projects/markdown/) **Mentor**: [Marek Marczykowski-Górecki](/team/) - diff --git a/developer/general/join.md b/developer/general/join.md index 577a25085..3e5e036a1 100644 --- a/developer/general/join.md +++ b/developer/general/join.md @@ -1,12 +1,11 @@ --- lang: en -layout: sidebar +layout: doc permalink: /join/ ref: 26 title: Join --- - The Qubes OS Project does not currently have any open positions. This page will be updated when open positions become available. In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index 0b45862c5..c15cae1af 100644 --- a/developer/general/package-contributions.md +++ b/developer/general/package-contributions.md @@ -6,7 +6,6 @@ ref: 29 title: Package Contributions --- - _This page is for developers who wish to contribute packages. If you want to install contributed packages, please see [installing contributed packages](/doc/installing-contributed-packages/)._ @@ -101,4 +100,3 @@ As the maintainer of the package, it is your privilege and responsibility to: If you do not wish to be the maintainer of your package, please let us know. If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package. - diff --git a/developer/general/research.md b/developer/general/research.md deleted file mode 100644 index 937af9296..000000000 --- a/developer/general/research.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -lang: en -layout: default -permalink: /research/ -redirect_from: -- /doc/qubes-research/ -- /en/doc/qubes-research/ -- /doc/QubesResearch/ -- /wiki/QubesResearch/ -ref: 139 -title: Research ---- - -Here are links to various research papers, projects, and blog posts that relate -to Qubes OS. diff --git a/developer/general/usability-ux.md b/developer/general/usability-ux.md index 212322992..75748bccc 100644 --- a/developer/general/usability-ux.md +++ b/developer/general/usability-ux.md @@ -6,7 +6,6 @@ ref: 31 title: Usability & UX --- - Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review [our style guide](/doc/style-guide/) for other design related information. diff --git a/developer/releases/1_0/release-notes.md b/developer/releases/1_0/release-notes.md index 4f46a77c1..9681a3e65 100644 --- a/developer/releases/1_0/release-notes.md +++ b/developer/releases/1_0/release-notes.md @@ -8,7 +8,6 @@ ref: 18 title: Qubes R1.0 Release Notes --- - Detailed release notes in [this blog post](https://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html). ## Known issues diff --git a/developer/releases/2_0/release-notes.md b/developer/releases/2_0/release-notes.md index 09d959536..a6e30028a 100644 --- a/developer/releases/2_0/release-notes.md +++ b/developer/releases/2_0/release-notes.md @@ -8,7 +8,6 @@ ref: 25 title: Qubes R2.0 Release Notes --- - Detailed release notes in [this blog post](https://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html) ## New features since 1.0 diff --git a/developer/releases/3_0/schedule.md b/developer/releases/3_0/schedule.md index 30111df58..512ee3ab9 100644 --- a/developer/releases/3_0/schedule.md +++ b/developer/releases/3_0/schedule.md @@ -8,7 +8,6 @@ ref: 20 title: Qubes R3.0 Release Schedule --- - | Date | Stage | | -----------:| ------------------------------------- | | 5 Sep 2015 | current-testing freeze before 3.0-rc3 | diff --git a/developer/releases/3_1/release-notes.md b/developer/releases/3_1/release-notes.md index 1b0bafcde..35d1bcd4b 100644 --- a/developer/releases/3_1/release-notes.md +++ b/developer/releases/3_1/release-notes.md @@ -6,7 +6,6 @@ ref: 16 title: Qubes R3.1 release notes --- - ## New features since 3.0 * Management Stack based of Salt Stack in dom0 - [documentation](/doc/salt/) @@ -64,4 +63,3 @@ for migrating of all of the user VMs. Alternatively you can [upgrade to R3.0 using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the instructions above. This will be time consuming process. - diff --git a/developer/releases/3_1/schedule.md b/developer/releases/3_1/schedule.md index dda8869d7..144818182 100644 --- a/developer/releases/3_1/schedule.md +++ b/developer/releases/3_1/schedule.md @@ -8,7 +8,6 @@ ref: 17 title: Qubes R3.1 Release Schedule --- - This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). | Date | Stage | diff --git a/developer/releases/3_2/release-notes.md b/developer/releases/3_2/release-notes.md index 37eca3299..547dff271 100644 --- a/developer/releases/3_2/release-notes.md +++ b/developer/releases/3_2/release-notes.md @@ -6,7 +6,6 @@ ref: 21 title: Qubes R3.2 release notes --- - ## New features since 3.1 * Management Stack extended to support in-VM configuration - [documentation](/doc/salt/) @@ -60,4 +59,3 @@ for migrating of all of the user VMs. Alternatively you can [upgrade to R3.1 using](/doc/releases/3.1/release-notes/#upgrading) first, then follow the instructions above. This will be time consuming process. - diff --git a/developer/releases/3_2/schedule.md b/developer/releases/3_2/schedule.md index 945fefa6e..ed769eeca 100644 --- a/developer/releases/3_2/schedule.md +++ b/developer/releases/3_2/schedule.md @@ -8,7 +8,6 @@ ref: 22 title: Qubes R3.2 Release Schedule --- - This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). | Date | Stage | diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md index b2ed70e61..b80a1959d 100644 --- a/developer/releases/4_0/release-notes.md +++ b/developer/releases/4_0/release-notes.md @@ -6,7 +6,6 @@ ref: 23 title: Qubes R4.0 release notes --- - New features since 3.2 ---------------------- @@ -106,4 +105,3 @@ There is no in-place upgrade path from earlier Qubes versions. The only supported option to upgrade to Qubes R4.0 is to install it from scratch and use [qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs. We also provide [detailed instruction](/doc/upgrade-to-r4.0/) for this procedure. - diff --git a/developer/releases/4_0/schedule.md b/developer/releases/4_0/schedule.md index fb8035fb9..98d4c1df1 100644 --- a/developer/releases/4_0/schedule.md +++ b/developer/releases/4_0/schedule.md @@ -8,7 +8,6 @@ ref: 24 title: Qubes R4.0 Release Schedule --- - This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule). | Date | Stage | diff --git a/developer/releases/notes.md b/developer/releases/notes.md index 71c1bd2c9..8059bf696 100644 --- a/developer/releases/notes.md +++ b/developer/releases/notes.md @@ -6,7 +6,6 @@ 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/) diff --git a/developer/releases/schedules.md b/developer/releases/schedules.md index afcd82e94..d2af2d6ef 100644 --- a/developer/releases/schedules.md +++ b/developer/releases/schedules.md @@ -6,7 +6,6 @@ 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/) diff --git a/developer/releases/todo.md b/developer/releases/todo.md index d3144959e..98179d89e 100644 --- a/developer/releases/todo.md +++ b/developer/releases/todo.md @@ -8,7 +8,6 @@ ref: 14 title: Release Checklist --- - *the checklist is probably unfinished* On -rc1 diff --git a/user/downloading-installing-upgrading/version-scheme.md b/developer/releases/version-scheme.md similarity index 99% rename from user/downloading-installing-upgrading/version-scheme.md rename to developer/releases/version-scheme.md index b07697813..da4ccf042 100644 --- a/user/downloading-installing-upgrading/version-scheme.md +++ b/developer/releases/version-scheme.md @@ -10,7 +10,6 @@ ref: 151 title: Version Scheme --- - Beginning with R3 release, we change (and formalise) the versioning scheme. From now on, it will be as follows. @@ -84,7 +83,7 @@ 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. -!["Release cycle"](/attachment/wiki/VersionScheme/release-cycle.svg) +!["Release cycle"](/attachment/doc/release-cycle.svg) Bug priorities -------------- @@ -155,4 +154,3 @@ Check installed version If you want to know which version you are running, for example to report an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal. - diff --git a/developer/services/admin-api-table.md b/developer/services/admin-api-table.md new file mode 100644 index 000000000..d5426419a --- /dev/null +++ b/developer/services/admin-api-table.md @@ -0,0 +1,11 @@ +--- +lang: en +layout: fullscreen +permalink: /doc/admin-api/table/ +ref: 249 +title: Admin API Table +--- + +This page displays the fullscreen table from [Admin API](/doc/admin-api/). + +{% include admin-api-table.md %} diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index 66e00b704..036782822 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -1,8 +1,9 @@ --- lang: en -layout: doc-full +layout: doc permalink: /doc/admin-api/ redirect_from: +- /doc/qubes-admin-api/ - /doc/mgmt/ - /doc/mgmt1/ - /doc/mgmt-architecture/ @@ -11,6 +12,8 @@ ref: 36 title: Admin API --- +_You may also be interested in the article +[Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)._ ## Goals @@ -37,7 +40,7 @@ TBD ## Components -![Admin API Architecture](/attachment/wiki/AdminAPI/admin-api-architecture.svg) +![Admin API Architecture](/attachment/doc/admin-api-architecture.svg) A central entity in the Qubes Admin API system is a `qubesd` daemon, which holds information about all domains in the system and mediates all actions (like @@ -58,93 +61,11 @@ yet documented. The API should be implemented as a set of qrexec calls. This is to make it easy to set the policy using current mechanism. -| call | dest | argument | inside | return | note | -| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- | -| `admin.vmclass.List` | `dom0` | - | - | `\n` | -| `admin.vm.List` | `dom0|` | - | - | ` class= state=\n` | -| `admin.vm.Create.` | `dom0` | template | `name= label=