Merge remote-tracking branch 'origin/main' into split-gpg2-install

.gitignore

@@ -1 +1,5 @@
 _build
+**/__pycache__/*
+uv.lock
+poetry.lock
+.venv

.readthedocs.yaml

@@ -21,5 +21,6 @@ python:
 formats:
 - pdf
 - epub
+- htmlzip
 
 

CONTRIBUTING.md

@@ -2,11 +2,11 @@
 
 Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
 Project's dedicated documentation repository! Please see [how to edit the
-documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/) for
+documentation](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-rst-documentation.html) for
 detailed contribution instructions.
 
 In addition, please take a moment to read our [documentation style
-guide](https://www.qubes-os.org/doc/documentation-style-guide/) before
+guide](https://doc.qubes-os.org/en/latest/developer/general/rst-documentation-style-guide.html) before
 contributing. These guidelines are important to maintaining high standards of
 quality, and following them will increase the likelihood that your contribution
 will be accepted.

README.md

@@ -1,11 +1,11 @@
 # Qubes OS Documentation
 
-Canonical URL: https://www.qubes-os.org/doc/
+Canonical URL: https://doc.qubes-os.org
 
 All [Qubes OS Project](https://github.com/QubesOS) documentation pages are
-stored as plain text files in this dedicated repository. By cloning and
+stored as plain reStructuredText 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.
 
 To contribute, please see [how to edit the
-documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/).
+documentation](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-rst-documentation.html).

_dev/index.rst

@@ -2,25 +2,13 @@
 Welcome to Qubes OS developer's documentation!
 ==============================================
 
-
 This is documentation for the source code. Please choose specific repostitory:
 
 .. toctree::
    :maxdepth: 1
 
-   core-admin <>
-.. _core-admin: /projects/core-admin
+   core-admin <https://dev.qubes-os.org/projects/core-admin>
+   core-admin-client <https://dev.qubes-os.org/projects/core-admin-client>
+   qubes-core-qrexec <https://dev.qubes-os.org/projects/qubes-core-qrexec>
 
-
-
-   core-admin-client <>
-.. _core-admin-client: /projects/core-admin-client
-
-
-
-
-
-Or see the main Qubes OS documentation <https://www.qubes-os.org/doc/>
-.. _the main qubes os documentation: https://www.qubes-os.org/doc/
-
-.
+Or see `the main Qubes OS documentation <https://www.qubes-os.org/doc/>`_.

attachment/doc/qubes-devices.svg

@@ -0,0 +1 @@
+<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="26.136" xmlns="http://www.w3.org/2000/svg" height="27.392" id="screenshot-de3f5f2e-651c-801e-8003-497b6baebd5c" viewBox="-5.227 -1.305 26.136 27.392" style="-webkit-print-color-adjust: exact;" fill="none" version="1.1"><g id="shape-de3f5f2e-651c-801e-8003-497b6baebd5c" rx="0" ry="0"><g id="shape-de3f5f2e-651c-801e-8003-497abeb7e6e4"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497abeb7e6e4"><path d="M10.235777410044818,2.5312758605410863 h6.5 a1,1 0 0 1 1,1 v6 a0,0 0 0 1 0,0 h-8.5 a0,0 0 0 1 0,0 v-6 a1,1 0 0 1 1,-1 z" x="9.235777410044818" y="2.5312758605410863" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.010645, -7.247096)" width="8.5" height="7" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad39f5ab2"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad39f5ab2"><rect rx="0" ry="0" x="14.469714467628762" y="5.386935461206235" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.700937, -8.437069)" width="2" height="2" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad9b00fdb"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad9b00fdb"><rect rx="0" ry="0" x="11.78496225215207" y="3.141472136746529" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 5.634982, -7.237668)" width="2.000000000000057" height="2.0000000000001137" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497aedbb68e1"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497aedbb68e1"><path d="M-1.725502478416331,7.459286392639228 h13.999999999999886 a0,0 0 0 1 0,0 v10 a6,6 0 0 1 -6,6 h-1.9999999999998863 a6,6 0 0 1 -6,-6 v-10 a0,0 0 0 1 0,0 z" x="-1.725502478416331" y="7.459286392639228" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 11.146652, 0.216988)" width="13.999999999999886" height="16" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g></g></svg>

conf.py

@@ -4,6 +4,7 @@ import os
 import sys
 from pathlib import Path
 
+# Append the path to custom extensions
 sys.path.append(str(Path('_ext').resolve()))
 
 # For the full list of options, see the documentation:
@@ -29,12 +30,15 @@ release = '4.2.4'
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-  'sphinx.ext.autosectionlabel',
-  'sphinxnotes.strike',
-  'sphinx_reredirects',
-  'youtube_frame',
+  'sphinx.ext.autosectionlabel',  # Automatically generate section labels
+  'sphinx.ext.intersphinx',  # Reference other doc projects
+  'sphinxnotes.strike', # Add strike-through text support
+  'sphinx_reredirects', # Manage redirects in the documentation
+  'sphinxext.opengraph', # Add Open Graph meta tags for social media sharing
+  'youtube_frame', # Embed YouTube videos
 ]
 
+# Redirects for specific URLs as fall back
 redirects = {
     "user/hardware/hcl":
         "https://www.qubes-os.org/hcl/",
@@ -42,27 +46,41 @@ redirects = {
         "https://www.qubes-os.org/downloads/mirrors/",
     "developer/general/visual-style-guide":
         "https://www.qubes-os.org/doc/visual-style-guide/",
-    "developer/general/website-style-guide":
-        "https://www.qubes-os.org/doc/website-style-guide/",
     "user/downloading-installing-upgrading/downloads":
         "https://www.qubes-os.org/downloads/",
-    "developer/general/how-to-edit-the-documentation":
-        "https://www.qubes-os.org/doc/how-to-edit-the-documentation/",
-}
 
+    # user/templates/windows URLs
+    "user/templates/windows/windows":
+        "/user/templates/windows/",
+    "user/templates/windows/windows-qubes-4-1":
+        "qubes-windows.html",
+    "user/templates/windows/windows-qubes-4-0":
+        "qubes-windows.html",
+    "user/templates/windows/qubes-windows-tools-4-1":
+        "qubes-windows-tools.html",
+    "user/templates/windows/qubes-windows-tools-4-0":
+        "qubes-windows-tools.html",
+    "user/templates/windows/migrate-to-4-1":
+        "qubes-windows-migrate.html",
+}
 
 # -- -- Options for highlighting ---------------------------------------------
 
+# Disable syntax highlighting
 highlight_language = 'none'
 
+# Set the Pygments style for syntax highlighting
+pygments_style = 'sphinx'
 
 # -- -- Options for source files ---------------------------------------------
 
+# Patterns to exclude from the source directory
 exclude_patterns = [
   '_*',
   '**/.*',
-  '**/*.txt'
+  '**/*.txt',
   'attachment',
+  '.venv',
 ]
 
 
@@ -85,15 +103,31 @@ html_static_path = ['attachment/doc']
 
 html_use_opensearch = "https://doc.qubes-os.org"
 
+html_logo = "attachment/icons/128x128/apps/qubes-logo-icon.png"
+html_favicon = "attachment/icons/favicon-16x16.png"
+
 # -- -- Options for the linkcheck builder ------------------------------------
 
 linkcheck_anchors = False
 linkcheck_ignore = [r'^https?://[^/\s]+\.onion']
 
 # -- Extensions configuration ------------------------------------------------
-
+# Prefix section labels with the document name
 autosectionlabel_prefix_document = True
 
+# Allows references to the docs in dev.qubes-os.org
+# i.e.: :doc:`core-admin:libvirt`
+intersphinx_mapping = {
+    'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
+    'core-admin-client': ('https://dev.qubes-os.org/projects/core-admin-client/en/latest/', None),
+    'core-qrexec': ('https://dev.qubes-os.org/projects/qubes-core-qrexec/en/stable/', None),
+}
+intersphinx_disabled_reftypes = ["*"]
+
+# Open Graph image for social media sharing
+ogp_image = "https://www.qubes-os.org/attachment/icons/qubes-logo-icon-name-slogan-fb.png"
+# Disable Open Graph image alt text
+ogp_image_alt = False
 
 # -- HTML configuration ------------------------------------------------------
 
@@ -110,8 +144,25 @@ html_context = {
 
 # -- -- Options for internationalisation -------------------------------------
 
+# Directories containing translation files
 locale_dirs = ['_translated']
 
 gettext_compact = False
 
 gettext_uuid = True
+
+# -- -- Options for markup ---------------------------------------------------
+
+# Define a block of reusable reStructuredText (reST) snippets, warnings etc. that Sphinx automatically appends to every source file before it is parsed
+rst_epilog = """
+.. |debian-codename| replace:: trixie
+.. |debian-version| replace:: 13
+.. |qubes-logo-icon| image:: /attachment/icons/128x128/apps/qubes-logo-icon.png
+   :height: 1em
+   :class: no-scaled-link
+   :alt: Qubes logo icon
+"""
+
+# -- -- Options for the nitpicky mode ----------------------------------------
+
+nitpicky = True

developer/building/qubes-builder-details.rst

@@ -4,7 +4,7 @@ Qubes builder details
 
 
 .. warning::
-      
+
       **Note:** This information concerns the old Qubes builder (v1). It supports only building Qubes 4.1 or earlier.The build process has been completely rewritten in `qubes-builder v2 <https://github.com/QubesOS/qubes-builderv2/>`__      . This can be used for building Qubes R4.1 and later, and all related components.
 
 Components Makefile.builder file

developer/building/qubes-builder-v2.rst

@@ -2,7 +2,6 @@
 Qubes builder v2
 ================
 
-
 This is a brief introduction to using Qubes Builder v2 to work with Qubes OS sources. It will walk you through installing and configuring Builder v2, and using it to fetch and build Qubes OS packages.
 
 For details and customization, use `Qubes OS v2 builder documentation <https://github.com/QubesOS/qubes-builderv2/>`__.
@@ -10,40 +9,29 @@ For details and customization, use `Qubes OS v2 builder documentation <https://g
 Overview
 --------
 
-
 In the second generation of Qubes OS builder, container or disposable qube isolation is used to perform every stage of the build and release process. From fetching sources to building, everything is executed inside an isolated *cage* (either a disposable or a container) using an *executor*. For every command that needs to perform an action on sources, like cloning and verifying Git repos, rendering a SPEC file, generating SRPM or Debian source packages, a new cage is used. Only the signing, publishing, and uploading stages are executed locally outside a cage.
 
 Setup
 -----
 
-
 This is a simple setup using a docker executor. This is a good default choice; if you don’t know which executor to use, use docker.
 
 1. First, decide what qube you are going to use when working with Qubes Builder v2. It can be an AppVM or a Standalone qube, with some steps different between the two.
 
 2. Installing dependencies
 
-   - If you want to use an app qube for developing, install dependencies in the template. If you are using a standalone, install them in the qube itself. Dependencies are specified in ``dependencies-*. txt`` files in the main builder directory, and you can install them easily in the following ways:
+   If you want to use an app qube for developing, install dependencies in the template. If you are using a standalone, install them in the qube itself. Dependencies are specified in ``dependencies-*. txt`` files in the main builder directory, and you can install them easily in the following ways:
 
+   - for Fedora, use:
 
-
-   1. for Fedora, use:
-
-
-
-   .. code:: console
+      .. code:: console
 
          $ sudo dnf install $(cat dependencies-fedora.txt)
          $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
 
+   - for Debian (note: some Debian packages require Debian version 13 or later), use:
 
-   2. for Debian (note: some Debian packages require Debian version 13 or later), use:
-
-
-
-
-
-   .. code:: console
+      .. code:: console
 
          $ sudo apt install $(cat dependencies-debian.txt)
          $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
@@ -57,7 +45,6 @@ This is a simple setup using a docker executor. This is a good default choice; i
          $ git clone https://github.com/QubesOS/qubes-builderv2
          $ cd qubes-builderv2/
 
-
 4. If you haven’t previously used docker in the current qube, you need to set up some permissions. In particular, the user has to be added to the ``docker`` group:
 
    .. code:: console
@@ -78,14 +65,9 @@ This is a simple setup using a docker executor. This is a good default choice; i
 
          binds+=( '/var/lib/docker' )
 
-
-
-
-
 Configuration
 -------------
 
-
 To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration file. You can use one of the sample files from the ``example-configs/`` directory; for a more readable ``builder.yml``, you can also include one of the files from that directory in your ``builder.yml``. An example ``builder.yml`` is:
 
 .. code:: yaml
@@ -116,19 +98,15 @@ To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration fil
         options:
           image: "qubes-builder-fedora:latest"
 
-
-
 Using Builder v2
 ----------------
 
-
 To fetch sources - in this example, for the ``core-admin-client`` package, you can use the following command:
 
 .. code:: console
 
       $ ./qb -c core-admin-client package fetch
 
-
 This will fetch the sources for the listed package and place them in ``artifacts/sources`` directory.
 
 To build a package (from sources in the ``artifacts/sources`` directory), use:
@@ -137,19 +115,16 @@ To build a package (from sources in the ``artifacts/sources`` directory), use:
 
       $ ./qb -c core-admin-client package fetch prep build
 
-
 or, if you want to build for a specific target (``host-fc37`` is a ``dom0`` using Fedora 37, ``vm-fc40`` would be a qube using Fedora 40 etc.), use:
 
 .. code:: console
 
       $ ./qb -c core-admin-client -d host-fc37 package fetch prep build
 
-
 If you want to fetch the entire Qubes OS source use the following:
 
 .. code:: console
 
       $ ./qb package fetch
 
-
 **caution**: some repositories might have additional requirements. You can disable repositories that are not needed in the ``example-configs/*.yml`` file you are using by commenting them out. In particular, ``python-fido2``, ``lvm`` and ``windows``-related repositories have special requirements.

developer/building/qubes-builder.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 Qubes builder
 =============
@@ -177,7 +179,7 @@ You can also modify sources somehow if you wish. Here are some basic steps:
 
 
 
-- You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo instead of “mainstream” - it contains newer (but less tested) versions
+  - You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo instead of “mainstream” - it contains newer (but less tested) versions
 
 
 

developer/code/code-signing.rst

@@ -111,6 +111,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
 
 
 3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check.
+
    This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history.
 
    .. code:: console

developer/code/coding-style.rst

@@ -49,7 +49,7 @@ General typographic conventions
 
 - **Maintain a decent amount of horizontal spacing**, e.g. add a space after ``if`` or before ``{`` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x*2+5) vs. (x * 2 + 5) is left to the developer’s judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: ``if ( condition )`` and use ones like this: ``if (condition)`` instead.
 
-- **Use single new lines** (‘\n’ aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (–). This will allow the source code to be easily viewable in various Windows-based programs.
+- **Use single new lines** (‘\\n’ aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (–). This will allow the source code to be easily viewable in various Windows-based programs.
 
 - **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
 

developer/code/source-code.rst

@@ -48,7 +48,7 @@ To update (git fetch) **all** of these repositories :
 
 .. code:: console
 
-      find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \;
+      $ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \;
 
 
 
@@ -61,6 +61,7 @@ How to Send Patches
 If you want to :ref:`contribute code <introduction/contributing:contributing code>` to the project, there are two ways. Whichever method you choose, you must :doc:`sign your code </developer/code/code-signing>` before it can be accepted.
 
 - **Preferred**: Use GitHub’s `fork & pull requests <https://guides.github.com/activities/forking/>`__.
+
   Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it’s a good idea to send a message to the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` in order to notify people who do not receive GitHub notifications.
 
 - Send a patch to the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` (``git format-patch``).

developer/debugging/test-bench.rst

@@ -157,7 +157,7 @@ Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Gene
 
 .. code:: console
 
-      ssh-keygen -t ecdsa -b 521
+      $ ssh-keygen -t ecdsa -b 521
 
 
 

developer/debugging/vm-interface.rst

@@ -199,11 +199,11 @@ Services called by dom0 to provide some VM configuration:
 
 
 
-  - ``xdgicon:NAME`` - search for NAME in standard icons theme
+    - ``xdgicon:NAME`` - search for NAME in standard icons theme
 
-  - ``-`` - get icon data from stdin (the caller), can be prefixed with format name, for example ``png:-``
+    - ``-`` - get icon data from stdin (the caller), can be prefixed with format name, for example ``png:-``
 
-  - file name
+    - file name
 
 
 

developer/debugging/windows-debugging.rst

@@ -23,7 +23,7 @@ Modifying the NIC of the target VM
 ----------------------------------
 
 
-You will need to create a custom libvirt config for the target VM. See `the documentation <https://dev.qubes-os.org/projects/core-admin/en/latest/libvirt.html>`__ for overview of how libvirt templates work in Qubes. The following assumes the target VM is named ``target-vm``.
+You will need to create a :doc:`custom libvirt config <core-admin:libvirt>` for the target VM. The following assumes the target VM is named ``target-vm``.
 
 - Edit ``/usr/share/qubes/templates/libvirt/xen.xml`` to prepare our custom config to override just the NIC part of the global template:
 

developer/general/developing-gui-applications.rst

@@ -63,7 +63,7 @@ If error should be thrown, you need to provide the error code and name, for exam
           b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00'
 
 
-For details of particular calls, you can use `Extending the mock Qubes object <#extending-the-mock-qubes-object>`__.
+For details of particular calls, you can use :ref:`developer/general/developing-gui-applications:extending the mock qubes object`.
 
 Available mocks
 ---------------

developer/general/gsod.rst

@@ -57,8 +57,8 @@ Timeline
 ^^^^^^^^
 
 
-.. list-table:: 
-   :widths: 15 15 
+.. list-table::
+   :widths: 15 15
    :align: center
    :header-rows: 1
 
@@ -70,15 +70,14 @@ Timeline
      - Update & extend how-to guides
    * - December
      - Final project evaluation and case study
-   
 
 
 Project budget
 ^^^^^^^^^^^^^^
 
 
-.. list-table:: 
-   :widths: 32 32 
+.. list-table::
+   :widths: 32 32
    :align: center
    :header-rows: 1
 
@@ -88,7 +87,6 @@ Project budget
      - $12,000
    * - TOTAL
      - $12,000
-   
 
 
 Additional information
@@ -113,22 +111,17 @@ Instructional video series
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-.. _the-projects-problem-1:
-
-
-The project's problem
-^^^^^^^^^^^^^^^^^^^^^
+Instructional video series: The project's problem
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 
 
 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-projects-scope-1:
 
-
-The project's scope
-^^^^^^^^^^^^^^^^^^^
+Instructional video series: The project's scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 
@@ -219,11 +212,10 @@ Below is an example of the content (which is already :doc:`documented </index>`)
 
 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.
 
-.. _measuring-the-projects-success-1:
 
 
-Measuring the project's success
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Instructional video series: Measuring the project's success
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 
@@ -250,7 +242,7 @@ Consolidate troubleshooting guides
 
 - Review existing :ref:`troubleshooting guides <troubleshooting>`
 
-- Review `issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+doc%22>`__ containing common troubleshooting steps (checking specific logs etc)
+- Review `issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22C%3A%20doc%22>`__ containing common troubleshooting steps (checking specific logs etc)
 
 - Propose updated, consolidated troubleshooting documentation, including its layout
 
@@ -258,7 +250,7 @@ Consolidate troubleshooting guides
 
 **Knowledge prerequisite**:
 
-- `Markdown <https://daringfireball.net/projects/markdown/>`__
+- `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
 
 
 
@@ -284,7 +276,7 @@ Improve Getting Started page
 
 - basic Qubes OS knowledge
 
-- `Markdown <https://daringfireball.net/projects/markdown/>`__
+- `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
 
 
 
@@ -310,7 +302,7 @@ Rewrite qrexec documentation
 
 **Knowledge prerequisite**:
 
-- `Markdown <https://daringfireball.net/projects/markdown/>`__
+- `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
 
 
 

developer/general/how-to-edit-the-rst-documentation.rst

@@ -0,0 +1,572 @@
+=============================
+How to edit the documentation
+=============================
+
+The Qubes OS documentation is stored as `reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`__ files in
+the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
+
+We use `Sphinx <https://www.sphinx-doc.org/>`__ for building and
+`Read The Docs (RTD) <https://readthedocs.com/>`__ for hosting.
+RTD is a `continuous‑documentation deployment platform <https://docs.readthedocs.com/platform/stable/continuous-deployment.html>`__ that can automatically
+detect changes in a GitHub repository and build the latest version of a documentation.
+
+.. figure:: /attachment/doc/rst-rtd-workflow.png
+    :alt: Qubes OS Documentation Workflow - once new documentation is written or changed, it is built and verified with Sphinx, pushed on GitHub/GitLab and hosted on RTD
+    :scale: 15 %
+    :align: center
+
+
+By cloning and regularly pulling from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository, users can maintain their
+own up-to-date offline copy of the Qubes documentation rather than
+relying solely on the web and either serve it locally or read the rST files directly.
+EPUB or PDF versions of Qubes OS documentation can also
+be downloaded from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__:
+
+.. figure:: /attachment/doc/rst-rtd-epub-pdf.png
+   :alt: Highlights from where one can download a ePUB or PDF of hte Qubes OS documentation deployed on RTD
+   :scale: 20 %
+   :align: center
+
+
+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 follow the steps below to open a pull
+request!
+
+
+How to submit a pull request
+============================
+
+We keep all the rST documentation in `qubes-doc <https://github.com/QubesOS/qubes-doc>`__,
+a dedicated Git repository hosted on `GitHub <https://github.com/>`__. Thanks to
+GitHub’s easy web interface, you can edit the documentation even if
+you’re not familiar with Git or the command line! All you need is a free
+GitHub account.
+
+A few notes before we get started:
+
+-  Since Qubes is a security-oriented project, every documentation change will be :ref:`reviewed <developer/general/how-to-edit-the-rst-documentation:security>` before it’s accepted. This allows us to maintain quality control and protect our users.
+
+-  To give your contribution a better chance of being accepted, please follow our :doc:`/developer/general/rst-documentation-style-guide`.
+
+-  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 :doc:`file an issue </introduction/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.
+
+-  Finally, if you’ve written something that doesn’t belong in qubes-doc but that would be beneficial to the Qubes community, please consider adding it to the :ref:`external documentation <developer/general/rst-documentation-style-guide:core vs. external documentation>`.
+
+(**Advanced users:** 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/>`__.
+You can continue reading :ref:`viewing_pr`.)
+
+Ok, let’s begin. Every documentation page has a :guilabel:`Edit on GitHub` link.
+
+|page-source-button|
+
+When you click on it, you’ll be taken to the source file — a reStructuredText (``.rst``) file — on GitHub.
+
+On this page, there will be a
+button to edit the file (if you are already logged in).
+
+|github-edit|
+
+If you are not logged in you can click on :guilabel:`Sign In`
+and you’ll be prompted to sign in with your GitHub username and password.
+You can also create a free account from here.
+
+|github-sign-in|
+
+If this is your first contribution to the documentation, you need to
+fork the repository (make your own copy).
+
+|fork1|
+
+It’s easy — just click the
+green :guilabel:`Create fork` button on the next page. This step is only needed the first
+time you make a contribution.
+
+
+|fork2|
+
+Now you can make your modifications.
+
+|fork3|
+
+.. You can also preview the changes by clicking the :guilabel:`Preview changes` tab.
+
+
+|edit|
+
+If you want to add images, read :ref:`how_to_add_images` and refer to :ref:`build_locally`
+if you want to locally verify that everything looks correct before submitting any changes.
+
+
+Once you’re finished, describe your changes at the bottom and click
+:guilabel:`Commit changes`.
+
+|commit|
+
+After that, you’ll see exactly what modifications you’ve made. At this
+stage, those changes are still in your own copy (fork) of the documentation.
+If everything looks good, send those changes to us by pressing
+the :guilabel:`Create pull request` button.
+
+
+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
+:guilabel:`Create pull request` button again. However, if you’re not ready for
+your PR to be reviewed or merged yet, please
+`make a draft PR instead <https://github.blog/news-insights/product-news/introducing-draft-pull-requests/>`__.
+
+|pull-request-confirm|
+
+If any of your changes should be reflected in the :doc:`documentation index (a.k.a. table of contents) </index>` — for example, if you’re adding a
+new page, changing the title of an existing page, or removing a page —
+please see :ref:`edit_doc_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.
+
+
+.. _viewing_pr:
+
+Viewing your pull request on RTD
+--------------------------------
+
+Every time you push a commit to your pull request, a build on RTD will be triggered.
+To view your PR you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__,
+find the last build of your PR and click on it:
+
+|pull-request-builds|
+
+There you can view the rendered docs or inspect the logs for errors:
+
+|pull-request-build|
+
+You can also just head straight to the following url: ``https://qubes-doc--<PR-NUMBER>.org.readthedocs.build/en/<PR-NUMBER>/``.
+
+
+Tips & Tricks
+-------------
+
+- Pull upstream changes into your fork regularly. Diverging too far from main can be cumbersome to update at a later stage.
+- To pull in upstream changes:
+
+  .. code:: console
+
+   $ git remote add upstream https://github.com/QubesOS/qubes-doc.git
+   $ git fetch upstream
+
+- Check the log and the current changes, before merging:
+
+  .. code:: console
+
+   $ git log upstream/main
+
+- Then merge the changes that you fetched:
+
+  .. code:: console
+
+   $ git merge upstream/main
+
+Keep your pull requests limited to a single issue, pull requests should be as atomic as possible.
+
+.. _edit_doc_index:
+
+TL;DR: How to edit the documentation index
+==========================================
+
+For a more comprehensive guide to the rST syntax and pitfalls please refer to the :doc:`/developer/general/rst-documentation-style-guide`.
+
+The source file for the :doc:`documentation index (a.k.a. table of contents) </index>` is
+`index.rst <https://github.com/QubesOS/qubes-doc/blob/main/index.rst>`__.
+
+
+:file:`index.rst` contains information about the hierarchy between the files in the documentation and/or
+the connection between them. `toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`__
+is the rST directive which defines the table of contents.
+
+If you want to add a newly created documentation file, do so as follows:
+
+.. code-block:: rst
+
+   .. toctree:
+      /path/to/old_doc_file_name
+      /path/to/new_doc_file_name
+
+
+Editing this file will change what appears on the documentation index.
+
+Please always be mindful that rST syntax is sensitive to indentation (3 spaces)!
+
+.. _how_to_add_images:
+
+TL;DR: How to add images
+========================
+
+For a more comprehensive guide to the rST syntax and pitfalls please refer to the :doc:`/developer/general/rst-documentation-style-guide`.
+
+Images reside inside the `qubes-doc repository <https://github.com/QubesOS/qubes-doc/>`__ in the directory `attachment/doc <https://github.com/QubesOS/qubes-doc/tree/main/attachment/doc>`__.
+
+To add an image to a page, use the following syntax:
+
+.. code-block:: rst
+
+   .. figure:: /attachment/doc/r4.0-snapshot12.png
+     :alt: Qubes desktop screenshot depicting <description>
+
+
+If you want to add a caption to the image, you may do so using the optional ``caption`` of the `figure directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`__.
+Another way without a caption is to use the `image directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`__.
+
+Then, add your image(s) in a the :file:`attachment/doc` folder in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__
+repository using the same path and filename.
+This is the only permitted way to include images. Do not link to images on other websites.
+
+.. _cross_referencing:
+
+TL;DR: Cross-referencing
+========================
+
+For a more comprehensive guide to the rST syntax and pitfalls please refer to the :doc:`/developer/general/rst-documentation-style-guide`.
+
+When referencing to an existing rST file use the ``:doc:`` `role <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc>`__ as in
+
+.. code-block:: rst
+
+  how to :doc:`contribute code </introduction/contributing>` do [...]
+
+When referencing to a section in an existing rST file use the ``:ref:`` `role <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref>`__ as in
+
+.. code-block:: rst
+
+  See the :ref:`USB Troubleshooting guide <user/troubleshooting/usb-troubleshooting:usb vm does not boot after creating and assigning usb controllers to it>` for [...]
+
+Use the path to the file starting from the root of qubes-doc repository, without any leading slash ``/`` and without the ``.rst`` file ending. The section name is usually taken as is in small caps.
+
+Some special cases are as follows (here the emphasis is on the ``"`` in the sections's title:
+
+.. code-block:: rst
+
+   the :ref:`VM Troubleshooting <user/troubleshooting/vm-troubleshooting:"no match found" when trying to install a template>`.
+
+which will point to :ref:`this section <user/troubleshooting/vm-troubleshooting:"no match found" when trying to install a template>`.
+
+.. code:: rst
+
+   we :ref:`distrust the infrastructure <introduction/faq:what does it mean to "distrust the infrastructure"?>`
+
+which will refer to :ref:`this section <introduction/faq:what does it mean to "distrust the infrastructure"?>`.
+
+
+For further options and use cases please refer to `Cross-references <https://www.sphinx-doc.org/en/master/usage/referencing.html>`__.
+
+
+Qubes OS rST configuration
+==========================
+
+:file:`qubes-doc` directory contains a build configuration file named :file:`conf.py`, used by Sphinx
+to define `input and output behaviour <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__.
+It contains settings and extensions that define how the documentation will be generated.
+You can find it `here <https://github.com/QubesOS/qubes-doc/blob/main/conf.py>`__.
+
+You can also find a :file:`readthedocs.yml` `file <https://github.com/QubesOS/qubes-doc/blob/main/.readthedocs.yaml>`__
+which tells RTD how to build the documentation. It defines the build environment, Python version, required dependencies,
+and which Sphinx configuration to run. Thus RTD automatically generates and hosts the docs.
+
+
+Extensions
+----------
+
+We use several Sphinx `extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`__
+as defined in :file:`conf.py`, as well a simple custom one to embed YouTube videos,
+which can be found `here <https://github.com/QubesOS/qubes-doc/tree/main/_ext>`__.
+
+
+.. _build_locally:
+
+Building the rST documentation locally
+======================================
+
+
+In order to build the Qubes OS rST documentation locally clone the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository
+(or your forked one if you want to submit a pull request).
+
+
+It is recommended to use a virtual environment, f.ex.
+`venv <https://docs.python.org/3/library/venv.html>`__,
+`poetry <https://python-poetry.org/>`__ or `uv <https://docs.astral.sh/uv/>`__.
+In the following section there is a sample setup to prepare local environments
+for building Qubes OS rST documentation.
+
+Using venv
+----------
+
+
+Creating a Python environment with venv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+1. **Install needed packages and clone the repository**
+
+   .. code-block:: console
+
+      $ sudo apt install git python3-dev python3.11-venv
+      $ git clone https://github.com/QubesOS/qubes-doc.git
+      $ cd qubes-doc
+
+2.  **Create a virtual environment**
+
+   Create and enter the virtual environment.
+
+   .. code-block:: console
+
+      $ python3 -m venv .venv
+      $ . .venv/bin/activate
+      (.venv) $ echo "$VIRTUAL_ENV"
+
+   .. note::
+
+      You will have to activate the environment every time a new shell is opened.
+
+2.  **Install Sphinx and Required Extensions**
+
+   Install Sphinx and the necessary extensions (:program:`sphinx-autobuild`, :program:`sphinx-lint`).
+
+   .. code-block:: console
+
+      (.venv) $ pip install -r requirements.txt sphinx-lint sphinx-autobuild
+
+
+Linting the documentation from venv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+1.  **Run Linting**
+
+   The `sphinx-lint` extension checks for common issues like missing references, invalid directives,
+   or formatting errors. Run the linting step using the :program:`sphinx-lint` command.
+
+   .. code-block:: console
+
+      (.venv) $ sphinx-lint -i .venv .
+
+
+2.  **Run Link Checker**
+
+   The `sphinx-linkcheck` extension verifies the validity of all external and internal links.
+
+   The results will be written to the :file:`_build/linkcheck` directory with a detailed report in :file:`output.txt` or :file:`output.json` files
+   of all checked links and their status (e.g., OK, broken, timeout).
+
+   .. code-block:: console
+
+      (.venv) $ sphinx-build -b linkcheck . _build/linkcheck
+
+
+Building the documentation from venv
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+-  **Build Documentation**
+
+   Use `sphinx-build` with the `-v` (verbose) flag to generate detailed output during the build process.
+   The build command specifies the source directory (current directory :file:`.`, :file:`qubes-doc` in this case), the output directory (:file:`_build/html`), and the builder (`html`).
+
+   .. code-block:: console
+
+      (.venv) $ sphinx-build -v -b html . _build/html
+
+
+   The build command specifies the source directory (:file:`qubes-doc`), the output directory (:file:`_build/html`), and the builder (`html`).
+   The build command will process all source files in the :file:`qubes-doc` directory, generate HTML output in the :file:`_build/html` directory, and print detailed build information to the console.
+   Pay attention to errors and warning in the output!
+   Please do not introduce any new warnings and fix all errors.
+
+
+-  **Use sphinx-autobuild for development**
+
+   For an active development workflow, you can use `sphinx-autobuild` to automatically rebuild the documentation
+   and refresh browser whenever a file is saved. `sphinx-autobuild` starts a web server at `http://127.0.0.1:8000`,
+   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the :file:`qubes-doc` directory.
+
+   .. code-block:: console
+
+      (.venv) $ sphinx-autobuild . _build/html
+
+Using poetry
+------------
+
+
+You can also use `uv <https://docs.astral.sh/uv/getting-started/>`__ if you wish.
+
+Creating a Python environment with poetry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+1. `Install poetry <https://python-poetry.org/docs/#installation>`__ and git and clone the repository.
+
+   .. code-block:: console
+
+      $ sudo apt install git
+      $ git clone https://github.com/QubesOS/qubes-doc.git
+      $ cd qubes-doc
+
+
+2.  **Install Sphinx and Required Extensions**
+
+   Install Poetry, Sphinx and the necessary extensions (`sphinx-autobuild`, `sphinx-lint`).
+   A :file:`pyproject.toml` file is `provided <https://github.com/QubesOS/qubes-doc/blob/main/pyproject.toml>`__.
+
+   .. code-block:: console
+
+      $ curl -sSL https://install.python-poetry.org | python3 -
+      $ poetry config virtualenvs.in-project true  # optional
+      $ poetry install
+
+   .. hint::
+
+      If you would like to avoid prefixing commands with :program:`poetry run`, you can source the virtual environment with ``eval $(poetry env activate)`` on every new shell session. Note that when enabling ``virtualenvs.in-project``, you will find the virtual environment in the project root directory undre ``.venv``, same place the ``venv`` instructions uses.
+
+Linting the documentation with peotry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+1.  **Run Linting**
+
+   The `sphinx-lint` extension checks for common issues like missing references, invalid directives,
+   or formatting errors. Run the linting step using the :program:`sphinx-lint` command.
+
+   .. code-block:: console
+
+      $ poetry run sphinx-lint -i .venv .
+
+
+2.  **Run Link Checker**
+
+   The `sphinx-linkcheck` extension verifies the validity of all external and internal links.
+
+   The results will be written to the :file:`_build/linkcheck` directory with a detailed report in :file:`output.txt` or :file:`output.json` files
+   of all checked links and their status (e.g., OK, broken, timeout).
+
+   .. code-block:: console
+
+      $ poetry run sphinx-build -b linkcheck . _build/linkcheck
+
+
+Building the documentation with poetry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+-  **Build Documentation**
+
+   Use `sphinx-build` with the `-v` (verbose) flag to generate detailed output during the build process.
+   The build command specifies the source directory (current directory :file:`.`, :file:`qubes-doc` in this case), the output directory (:file:`_build/html`), and the builder (`html`).
+
+   .. code-block:: console
+
+      $ poetry run sphinx-build -v -b html . _build/html
+
+
+   The build command specifies the source directory (:file:`qubes-doc`), the output directory (:file:`_build/html`), and the builder (`html`).
+   The build command will process all source files in the :file:`qubes-doc` directory, generate HTML output in the :file:`_build/html` directory, and print detailed build information to the console.
+   Pay attention to errors and warning in the output!
+   Please do not introduce any new warnings and fix all errors.
+
+
+-  **Use sphinx-autobuild for development**
+
+   For an active development workflow, you can use `sphinx-autobuild` to automatically rebuild the documentation
+   and refresh browser whenever a file is saved. `sphinx-autobuild` starts a web server at `http://127.0.0.1:8000`,
+   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the :file:`qubes-doc` directory.
+
+   .. code-block:: console
+
+      $ poetry run sphinx-autobuild . _build/html
+
+
+Editor
+------
+
+An editor you can use is `ReText <https://github.com/retext-project/retext>`__ but any editor would do.
+
+
+.. code-block:: console
+
+   $ sudo apt install libxcb-cursor0
+   $ python3 -m venv .venv
+   $ . .venv/bin/activate
+   $ pip3 install ReText
+
+
+Security
+========
+
+Also see: :ref:`FAQ: Why is the documentation hosted on ReadTheDocs as opposed to the website? <introduction/faq:why is the documentation hosted on readthedocs as opposed to the 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 :ref:`external documentation <index: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 ``<LATEST_COMMIT>`` (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 or
+about how to edit the documentation, please post it on the `forum <https://forum.qubes-os.org/>`__
+or send it to the appropriate :doc:`mailing list </introduction/support>`. If you see that something in the
+documentation should be fixed or improved, please
+:ref:`contribute <developer/general/how-to-edit-the-rst-documentation:how to submit a pull request>` the change yourself. To
+report an issue with the documentation, please follow our standard
+:doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an
+issue with the documentation, you will likely be asked to submit a pull
+request for it, unless there is a clear indication in your report that
+you are not willing or able to do so.)
+
+
+.. |page-source-button| image:: /attachment/doc/doc-pr_01_page-source-button-rtd.png
+   :alt: Highlights the Edit Source Button to GitHub sources on doc.qubes-os.org
+.. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit-rst.png
+   :alt: Highlights the Sign-In on GitHub
+.. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in-rst.png
+   :alt: GitHub Login
+.. |fork1| image:: /attachment/doc/doc-pr_04_fork-rst1.png
+   :alt: Highlights the Fork Button on GitHub for the qubes-doc repository
+.. |fork2| image:: /attachment/doc/doc-pr_04_fork-rst2.png
+   :alt: Highlights the Create Fork Button on GitHub when forking the qubes-doc repository
+.. |fork3| image:: /attachment/doc/doc-pr_04_fork-rst3.png
+   :alt: Forked qubes-doc repository on GitHub
+.. |edit| image:: /attachment/doc/doc-pr_05_edit-rst.png
+   :alt: Highlights the edit options for an rst file in the GitHub forked qubes-doc repository
+.. |commit| image:: /attachment/doc/doc-pr_06_commit-msg-rst.png
+   :alt: Highlights the commit changes button on GitHub
+.. |pull-request-confirm| image:: /attachment/doc/doc-pr_09_create-pr-rst.png
+   :alt: Highlights the create pull request button on GitHub when creating a pull request
+.. |pull-request-builds| image:: /attachment/doc/doc-pr_10_view-pr-rtd.png
+   :alt: Highlights the pull request <number> and its build in the build list on RTD
+.. |pull-request-build| image:: /attachment/doc/doc-pr_11_view-pr-rtd.png
+   :alt: Highlights the View Docs button in a specific build for a pull request <number> on RTD

developer/general/how-to-edit-the-website.rst

@@ -0,0 +1,220 @@
+=======================
+How to edit the website
+=======================
+
+
+*Also see the* :doc:`Website style guide </developer/general/website-style-guide>`.
+
+The Qubes OS website content is stored in the `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ repository and its submodules.
+By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of the Qubes OS website rather than relying solely on the web.
+
+This guide refers only to the hosted website on `qubes-os.org <https://qubes-os.org>`__.
+It was the reference point before the documentation was converted from
+Markdown to reStructuredText and remains as a guide if you want to contribute
+to the Qubes OS website.
+If you want to contribute to the Qubes OS documentation, please visit :doc:`How to edit the documentation </developer/general/how-to-edit-the-rst-documentation>`.
+
+How to submit a pull request
+----------------------------
+
+We keep all relevant files in `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__, as well as
+`qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__,
+`qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ and `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ - dedicated Git repositories
+hosted on `GitHub <https://github.com/>`__.
+
+A few notes to consider:
+
+- Since Qubes is a security-oriented project, every change will be :ref:`reviewed <developer/general/how-to-edit-the-website:security>` before it’s accepted. This allows us to maintain quality control and protect our users.
+- To give your contribution a better chance of being accepted, please follow our :doc:`website style guide </developer/general/website-style-guide>`.
+- 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 :doc:`file an issue </introduction/issue-tracking>` for it first so that we can make sure we’re on the same page before significant works begins.
+- Finally, if you’ve written something that doesn’t belong in `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ but would be beneficial to the Qubes community, please consider adding it to the :doc:`documentation </developer/general/how-to-edit-the-rst-documentation>` or the :ref:`external documentation <developer/general/rst-documentation-style-guide:core vs. external documentation>`.
+
+For an example how to submit a pull request please refer to the example given in :ref:`How to submit a pull request <developer/general/how-to-edit-the-rst-documentation:how to submit a pull request>` with the documentation.
+
+The Qubes OS website
+--------------------
+
+The Qubes OS site is generated with `Jekyll <https://jekyllrb.com/>`__, a static‑site engine that transforms Markdown, HTML, and data files into a fully rendered, deploy‑ready website.
+
+These are the relevant repositories:
+
+- the main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__, as well as its submodules:
+- `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__,
+- `qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ and
+- `qubes-posts <https://github.com/QubesOS/qubes-posts>`__.
+
+
+The contents of the `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ repository is reflected in the `News section <https://www.qubes-os.org/news/>`__:
+
+|news-section|
+
+This repository is maintained by the Qubes OS team and serves the purpose of announcing relevant project news. This repository and its contents should be left as is.
+
+The contents of the `qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ repository can be seen in the `Hardware Compatibility List (HCL) table <https://www.qubes-os.org/hcl/>`__:
+
+|hcl-section|
+
+This repository is also maintained by the Qubes OS team and its contents should be left as is. Of course you can :ref:`generate and submit a Hardware Compatibility List (HCL) report <user/hardware/how-to-use-the-hcl:generating and submitting new reports>` at any time.
+
+The `qubes-attachment <https://github.com/QubesOS/qubes-hcl>`__ repository contains images and files that are used by or referenced in the website.
+Here you can add new images if needed.
+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.
+
+
+Quick intro to Jekyll
+---------------------
+
+
+`Jekyll <https://jekyllrb.com/>`__ is a static‑site generator that turns plain‑text files (Markdown, HTML, YAML, etc.) into a full website you can host on GitHub Pages. It works by:
+
+- *Reading data*: YAML front‑matter in :file:`pages/_posts` and files under :file:`_data` give variables you can reuse.
+- *Applying layouts*: HTML layout files wrap your content, letting you keep a consistent header/footer, navigation, etc.
+- *Processing includes*: Reusable snippets (HTML/`Liquid <https://jekyllrb.com/docs/liquid/>`__) can be dropped into pages.
+- *Compiling assets*: SASS/SCSS files become CSS, JavaScript is copied as‑is.
+- *Generating the output*: All source files are rendered into a :file:`_site` folder that contains the ready‑to‑serve static files.
+
+The main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ contains the following directories:
+
+.. code:: bash
+
+  ├── data          # ← YAML files with key‑value pairs used throughout the site
+  │   └── *.yml     # e.g. site settings, navigation menus
+  │
+  ├── _doc          # ← Empty Markdown documentation files (previously a submodule “qubes‑doc”)
+  │   └── *.md      # with redirects to RTD
+  │
+  ├── _hcl          # ← “qubes‑hcl” submodule – custom content for HCL pages
+  │   └── ...       #
+  │
+  ├── _includes     # ← Reusable HTML/Liquid snippets
+  │   └── *.html    # include with {% include filename.html %} in Markdown or layouts
+  │
+  ├── _layouts      # ← Page templates that wrap content
+  │   └── *.html    # e.g. default.html, news.html, hcl.html – edit to change overall page structure
+  │
+  ├── _posts        # ← “qubes‑post” submodule – blog‑style entries
+  │   └── *_*.md    # each post has YAML front‑matter
+  │
+  ├── _sass         # ← Source SASS/SCSS files
+  │   └── *.scss    #
+  │
+  ├── _utils        # ← Helper scripts or small utilities used by the site
+  │   └── *.py/.sh  # usually not touched unless you need custom build steps
+  │
+  ├── attachment    # ← “qubes‑attachment” submodule – extra downloadable files
+  │   └── *.*       # place PDFs, images, etc. that you want linked from the site
+  │
+  ├── css           # ← CSS files
+  │   └── *.css     #
+  │
+  ├── fontawesome   # ← Font Awesome CSS and font files
+  │   └── *.css/.ttf
+  │
+  ├── fonts         # ← Additional font files used by the site
+  │   └── *.woff/.ttf
+  │
+  ├── js            # ← JavaScript assets
+  │   └── *.js      # edit to add or modify interactive behaviour
+  │
+  ├── news          # ← Templates for generating news‑type content
+  │   └── *.md      # often paired with a layout (e.g., news.html)
+  │
+  └── pages         # ← Stand‑alone pages (donate, team, about, etc.)
+    └── *.md/.html  # each file becomes a page at /<filename>/
+
+Cheatsheet
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 50
+   :align: center
+
+   * - Goal
+     - Where to edit
+     - Typical steps
+   * - Change site‑wide text (e.g., site title, navigation)
+     - ``_data/*.yml``, ``_config.yml``
+     - Update the key/value pair, then rebuild.
+   * - Modify the look of all pages
+     - ``_layouts/*.html`` and/or ``_sass/*.scss``
+     - Edit the HTML skeleton or SASS variables, then run preview.
+   * - Insert a reusable component (e.g., a call‑out box)
+     - ``_includes/*.html``
+     - Create the snippet, then reference it with ``{% include snippet.html %}`` in any page or post.
+   * - Add a new static asset (image, PDF)
+     - ``attachment/`` (`qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__)
+     - Drop the file there and link to it using a relative URL.
+   * - Update JavaScript behavior
+     - ``js/*.js``
+     - Edit the script, ensure it’s referenced in the appropriate layout or page.
+
+
+How to serve the website locally
+--------------------------------
+
+You can serve the website offline on your local machine by following `these instructions <https://github.com/QubesOS/qubesos.github.io#instructions>`__ or the instructions below.
+This can be useful for making sure that your changes render the way you expect, especially when your changes affect formatting, images, tables, styling, etc.
+
+1. Create a template qube:
+
+.. code:: console
+
+  $ qvm-clone debian-12-minimal jekyll-tvm
+
+2. Install packages:
+
+.. code:: console
+
+  $ apt install qubes-core-agent-networking
+  $ apt install ruby-full build-essential zlib1g-dev vim
+  $ apt install qubes-core-agent-passwordless-root
+  $ apt install firefox-esr git
+
+
+3. Create a ``jekyll-app-vm`` based on the ``jekyll-tvm`` template, install and configure in ``jekyll-app-vm``:
+
+.. code:: console
+
+  $ echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
+  $ echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
+  $ echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
+  $ source ~/.bashrc
+  $ gem install jekyll bundler
+  $ find . -name gem
+  $ bundle config set --local path '/home/user/.local/share/gem/'
+  $ git clone -b new-main --recursive https://github.com/QubesOS/qubesos.github.io.git; cd qubesos.github.io/
+  $ bundle install
+  $ bundle exec jekyll serve --incremental
+
+You can view the local site at `http://localhost:4000 <http://localhost:4000>`__.
+
+Quick checklist for a typical edit
+----------------------------------
+
+- Locate the right folder – use the table above to know where the content lives.
+- Edit the file – Markdown for content, HTML/SASS for layout/style, YAML for data.
+- Run a local build to verify the change looks correct.
+- Commit & push – include a clear commit message describing the edit.
+- Create a Pull Request
+
+Feel free to ask if you need more detail on any specific folder or on how to set up the development environment!
+
+Security
+--------
+
+*Also see:* :ref:`Should I trust this website? <introduction/faq:should i trust this website?>`
+
+All pull requests (PRs) against `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ must pass review prior to be merged. 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 ``<LATEST_COMMIT>``" (or similar). The website maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the website 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 website 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 website or about how to edit the it, please post it on the `forum <https://forum.qubes-os.org/>`__ or send it to the appropriate :doc:`mailing list </introduction/support>`. If you see that something in the website should be fixed or improved, please :ref:`contribute <developer/general/how-to-edit-the-website:how to submit a pull request>` the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an issue with the website, you will likely be asked to submit a pull request for it, unless there is a clear indication in your report that you are not willing or able to do so.)
+
+.. |news-section| image:: /attachment/doc/website_news_section.png
+   :alt: Depicts the News section of the Qubes OS website
+.. |hcl-section| image:: /attachment/doc/website_hcl.png
+   :alt: Depicts the Hardware Compatibility List table on the Qubes OS website

developer/general/package-contributions.rst

@@ -35,7 +35,7 @@ Contribution Procedure
 
 Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>`. Once you have a package that’s ready to become part of Qubes OS, please follow this procedure:
 
-1. Ensure that your package satisfies the `Inclusion Criteria <#inclusion-criteria>`__.
+1. Ensure that your package satisfies the :ref:`developer/general/package-contributions:inclusion criteria`.
 
 2. If your code isn’t already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called `qubes-skeleton <https://github.com/QubesOS-contrib/qubes-skeleton>`__.
 
@@ -43,7 +43,7 @@ Before you start putting serious work into a package, we recommend that you disc
 
 4. Create an issue in `qubes-issues <https://github.com/QubesOS/qubes-issues/issues/>`__ with the title ``[Contribution] your-package-name``. Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. Please note that the Qubes core developers are very busy. If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. If this happens, please do not be discouraged. If you think they may have forgotten about your pending contribution, you may “bump” your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month). We appreciate your understanding!
 
-5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ organization on GitHub as public recognition of your contribution (but without push access; see `Review Procedure <#review-procedure>`__), and `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue.
+5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ organization on GitHub as public recognition of your contribution (but without push access; see :ref:`developer/general/package-contributions:review procedure`), and `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue.
 
 
 
@@ -59,7 +59,7 @@ Review Procedure
 ----------------
 
 
-This review procedure covers both original package contributions (see `Contribution Procedure <#contribution-procedure>`__) and all subsequent updates to those packages, including updates from the original package contributor (see `Update Procedure <#update-procedure>`__). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the `Package Maintainer <#package-maintainers>`__ (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
+This review procedure covers both original package contributions (see :ref:`developer/general/package-contributions:contribution procedure`) and all subsequent updates to those packages, including updates from the original package contributor (see :ref:`developer/general/package-contributions:update procedure`). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the :ref:`Package Maintainer <developer/general/package-contributions:package maintainers>` (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
 
 The review procedure is as follows:
 
@@ -97,7 +97,7 @@ Package Maintainers
 
 If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. As the maintainer of the package, it is your privilege and responsibility to:
 
-- `Review <#review-procedure>`__ each pull request made against the package.
+- :ref:`Review <developer/general/package-contributions:review procedure>` each pull request made against the package.
 
 - Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
 

developer/general/research.rst

@@ -8,7 +8,7 @@ posts related to Qubes OS.
 Secure Software Development
 ===========================
 
-- `Security challenges for the Qubes build process <https://blog.invisiblethings.org/2016/05/30/build-security.html>`__ by Joanna Rutkowska, May 2016 
+- `Security challenges for the Qubes build process <https://blog.invisiblethings.org/2016/05/30/build-security.html>`__ by Joanna Rutkowska, May 2016
 
 
 Towards Trusted Hardware

developer/general/rst-documentation-style-guide.rst

@@ -0,0 +1,937 @@
+===========================================
+reStructuredText documentation style guide
+===========================================
+
+*Also see* :doc:`How to edit the documentation </developer/general/how-to-edit-the-rst-documentation/>`.
+
+This page explains the standards we follow for writing, formatting, and organizing the documentation.
+Please follow these guidelines and conventions when editing the rST documentation.
+For the standards governing the website (as opposed to the rST documentation hosted on `https://doc.qubes-os.org <https://doc.qubes-os.org>`__),
+please see the :doc:`Website style guide </developer/general/website-style-guide>`.
+If you wish to submit a pull request regarding content hosted on the website, please refer to
+:doc:`How to edit the website </developer/general/how-to-edit-the-website/>`.
+
+reStructuredText conventions
+----------------------------
+
+All the documentation is written in `reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`__. When making contributions, please observe the following style conventions.
+If you’re not familiar with reStructuredText syntax, `the Sphinx primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+is a great resource, as well as `this quick reStructuredText <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__.
+Please always be mindful that rST syntax is sensitive to indentation!
+
+
+Directives
+^^^^^^^^^^
+
+A `directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`__ is a generic block of explicit markup,
+provided by `Docutils <https://www.docutils.org/>`__ and extended by `Sphinx <https://www.sphinx-doc.org/>`__.
+Directives are used to insert non-paragraph content, such as images, tables, and code blocks.
+Example directives are:
+
+.. code:: rst
+
+   .. image::
+   .. code::
+   .. figure::
+
+Directives start with ``..``, followed by directive name, arguments, options, and indented content.
+
+Images
+""""""
+
+To include images (without a caption), use the ``image`` directive.
+You need to specify the path to the image and an alt text.
+
+.. code:: rst
+
+  .. image:: path/to/image.png
+     :alt: Alternative text
+     :width: 200px
+     :align: center
+
+Read The Docs and the HTML `sphinx-rtd-theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ in use
+have a responsive design, which allows the documentation to render appropriately across all screen sizes.
+
+Make sure to link only to images in the :file:`attachment/doc` folder of the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
+Do not attempt to link to images hosted on other websites.
+
+See also :ref:`how_to_add_images` for the further information and about using the ``figure`` directive.
+
+Lists
+"""""
+
+`Lists <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks>`__ can be bullet lists (\*, +, -), enumerated lists (1., 2., etc.), definition lists, field lists.
+
+Nested lists must be separated from the parent list items by blank lines:
+
+.. code:: rst
+
+  - Item 1
+  - Item 2
+
+    - Subitem 2.1
+    - Subitem 2.2
+
+  - Item 3
+
+Numbered lists can be autonumbered using the ``#`` sign.
+
+.. code:: rst
+
+  #. Item 1
+  #. Item 2
+
+    #. Subitem 2.1
+    #. Subitem 2.2
+
+  #. Item 3
+
+Item 3 will start at 1.
+
+Code blocks
+"""""""""""
+
+When writing code blocks, use syntax highlighting within the `code <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__
+or `code-block <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__.
+
+By specifying the language, you enable pygments, which show syntax color coding for that code sample (see `here <https://pygments.org/languages/>`__ for a list of supported languages).
+
+.. code:: rst
+
+   .. code:: language
+
+      code
+
+
+
+Use ``[...]`` for anything omitted.
+
+For inlining small code snippets you can use the `code role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-code>`__ as in
+
+.. code:: rst
+
+   `code:`:term:`qube``
+
+You can add line numbers to code examples with the ``:linenos:`` parameter.
+
+.. code:: rst
+
+    .. code:: python
+      :linenos:
+
+       def hello_world():
+         print("Hello, world!")
+
+
+You can have certain lines with the ``:emphasize-lines:`` parameter.
+
+.. code:: rst
+
+ .. code:: python
+   :emphasize-lines: 1,3,4
+
+
+
+For Python use ``python``.
+
+.. code:: rst
+
+    .. code:: python
+
+      string_var = 'python'
+
+For Bash use ``bash``.
+
+.. code:: rst
+
+    .. code:: bash
+
+       #!/bin/bash
+
+For a terminal session use ``console``.
+
+.. code:: rst
+
+    .. code:: console
+
+       $ echo "Hello"
+
+For text output use ``output``.
+
+.. code:: rst
+
+    .. code:: output
+
+       some output
+
+For text use ``text``.
+
+.. code:: rst
+
+    .. code:: text
+
+       some text
+
+
+Tables
+""""""
+
+We adhere to the list tables directive by docutils as described `here <https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table-1>`__.
+
+A simple example would be:
+
+    .. code:: rst
+
+        .. list-table::
+           :widths: 15 10
+           :align: center
+           :header-rows: 1
+
+           * - Header 1
+             - Header 2
+           * - Cell 1
+             - Cell 2
+           * - Cell 3
+             - Cell 4
+
+Admonitions, messages, and warnings
+"""""""""""""""""""""""""""""""""""
+
+`Admonitions, messages, and warnings <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings>`__ are 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 provided out of the box by Sphinx and rST.
+Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue <https://en.wikipedia.org/wiki/Alarm_fatigue>`__.
+
+Here are examples of several types of alerts:
+
+.. code:: rst
+
+    .. hint::
+       **Did you know?** The Qubes OS installer is completely offline. It doesn't
+       even load any networking drivers, so there is no possibility of
+       internet-based data leaks or attacks during the installation process.
+
+     .. note::
+       **Note:*</b>** Using Rufus to create the installation medium means that you
+       `wont be able <https://github.com/QubesOS/qubes-issues/issues/2051">`__
+       to choose the "Test this media and install Qubes OS" option mentioned in the
+       example below. Instead, choose the "Install Qubes OS" option.
+
+     .. warning::
+       **Note:** Qubes OS is not meant to be installed inside a virtual machine
+       as a guest hypervisor. In other words, **nested virtualization** is not
+       supported. In order for a strict compartmentalization to be enforced, Qubes
+       OS needs to be able to manage the hardware directly.
+
+     .. danger::
+       **Warning:** Qubes has no control over what happens on your computer
+       before you install it. No software can provide security if it is installed on
+       compromised hardware. Do not install Qubes on a computer you don't trust. See
+       installation security for more information.
+
+
+
+These render as:
+
+.. hint::
+       **Did you know?** The Qubes OS installer is completely offline. It doesn't
+       even load any networking drivers, so there is no possibility of
+       internet-based data leaks or attacks during the installation process.
+
+.. note::
+       **Note:** Using Rufus to create the installation medium means that you
+       `won't be able <https://github.com/QubesOS/qubes-issues/issues/2051>`__
+       to choose the "Test this media and install Qubes OS" option mentioned in the
+       example below. Instead, choose the "Install Qubes OS" option.
+
+.. warning::
+       **Note:** Qubes OS is not meant to be installed inside a virtual machine
+       as a guest hypervisor. In other words, **nested virtualization** is not
+       supported. In order for a strict compartmentalization to be enforced, Qubes
+       OS needs to be able to manage the hardware directly.
+
+.. danger::
+       **Warning:** Qubes has no control over what happens on your computer
+       before you install it. No software can provide security if it is installed on
+       compromised hardware. Do not install Qubes on a computer you don't trust. See
+       installation security for more information.
+
+
+Glossary
+""""""""
+
+The Sphinx `glossary directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary>`__
+is created with a simple ``.. glossary::`` block in :file:`/user/reference/glossary.rst`.
+Anywhere else in the documentation you can link to a term using the role: :code:`:term:`qube``
+which automatically generates a hyperlink to the glossary entry :term:`qube`.
+
+
+Roles
+^^^^^
+
+Sphinx uses interpreted text `roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__ to insert semantic markup into documents
+and thus enhance the readability and consistency of the documentation.
+
+Syntax is as follows:
+
+.. code:: rst
+
+   :rolename:`content`
+
+In Qubes OS documentation the `doc <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc>`__ and
+`ref <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref>`__ roles are used extensively
+as described in :ref:`cross_referencing`.
+
+Some of the roles used in the Qubes OS documentation so far are:
+
+- the ``:file:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file>`__
+- the ``:guilabel:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel>`__
+- the ``:menuselection:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection>`__
+- the ``:samp:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp>`__
+- the ``:kbd:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-kbd>`__
+
+Please continue using the above or new ones where appropriate.
+
+
+Cross referencing:
+^^^^^^^^^^^^^^^^^^
+
+- Use the `:doc:` role with a path and a custom link text:
+
+
+  .. code:: rst
+
+   :doc:`contributions </introduction/contributing>`.
+
+- Use the `:doc:` role with a path:
+
+  .. code:: rst
+
+   :doc:`/introduction/intro`
+
+- Use `:ref:` for specific sections and a custom link text
+
+  .. code:: rst
+
+
+   :ref:`What is Qubes OS? <introduction/intro:what is qubes os?>`
+
+- Use `:ref` only with a unique label above the specific section:
+
+  .. code:: rst
+
+    .. _cross_referencing:
+
+    TL;DR: Cross-referencing
+    ------------------------
+
+and link to the section from within the documentation using :code:`:ref:`cross_referencing``.
+
+
+For further information please see :ref:`cross_referencing`.
+
+External cross-referencing
+""""""""""""""""""""""""""
+
+You can make a cross-reference to any of the projects of the external developer's documentation (hosted on https://dev.qubes-os.org):
+
+* :doc:`core-admin <core-admin:index>`
+* :doc:`core-admin-client <core-admin-client:index>`
+* :doc:`core-qrexec <core-qrexec:index>`
+
+To do such a cross-reference, use the usual cross-reference syntax but with the following prefix: :samp:`{PROJECT_NAME}:` (replace :samp:`{PROJECT_NAME}` by the name of the project). As an example, if you want to link to the index of the core-admin documentation, use this:
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - reStructuredText markup
+     - output
+   * - .. code:: rst
+
+          :doc:`core-admin:index`
+
+     - :doc:`core-admin:index`
+
+This is equivalent to using ``:doc:`index``` inside the core-admin documentation. This works with any role like ``:ref:``, ``:option:``, etc.
+
+Even if it works without it, always prefix the external cross-references with the name of the project, to help other contributors and maintainers to figure out what is going on.
+
+.. note::
+
+   Intersphinx `can list all the available links <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#showing-all-links-of-an-intersphinx-mapping-file>`__ to another project with the following command:
+
+   .. code:: console
+
+       python3 -m sphinx.ext.intersphinx https://dev.qubes-os.org/projects/core-admin/en/latest/objects.inv
+
+   You can replace ``core-admin`` by any of the projects listed above.
+
+Hyperlink syntax
+^^^^^^^^^^^^^^^^
+
+
+Use non-reference-style links like
+
+.. code:: rst
+
+    `website <https://example.com/>`__
+
+Do *not* use reference-style links like
+
+.. code:: rst
+
+   Some text link_
+
+    :: _link:: https://example.org
+
+This facilitates the localization process.
+
+Take a look also at :ref:`cross_referencing`.
+
+
+Relative vs. absolute links
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Always use relative rather than absolute paths for internal website links.
+For example, use:
+
+.. code:: rst
+
+  text :doc:`contribute code </introduction/contributing>` text
+
+instead of:
+
+.. code:: rst
+
+  text `contribute code <https://doc.qubes-os.org/introduction/contributing.html>` text
+
+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 <https://www.qubes-os.org/security/qsb/>`__ and `Canaries <https://www.qubes-os.org/security/canary/>`__), since they’re not hyperlinks
+- Git repo files like ``README.md`` and ``CONTRIBUTING.md``, since they’re not part of the documentation itself.
+
+
+This rule is important because using absolute URLs for internal website links breaks:
+
+- Serving the documentation offline
+- Documentation localization
+- Generating offline documentation
+
+
+HTML and CSS
+^^^^^^^^^^^^
+
+Do not write HTML inside rST documents. In particular, never include HTML or CSS for styling, formatting, or white space control.
+That belongs in the (S)CSS files instead.
+
+
+Headings
+^^^^^^^^
+
+Sectioning uses underlines with different characters (=, -, ^, ", ', ~) to create different levels of headings.
+This is also the recommended order provided.
+It doesn't matter which characters you use in which order to mark a title, subtitle etc,
+as long as they are in consistent use across the documentation.
+
+Qubes OS uses the convention in `Python Developer’s Guide for documenting <https://devguide.python.org/documentation/markup/#sections>`__ which are as follows:
+
+
+.. code:: text
+
+    # with overline, for parts
+    * with overline, for chapters
+    = for sections
+    - for subsections
+    ^ for subsubsections
+    " for paragraphs
+
+A simple example of how this is used in the Qubes OS documentation:
+
+.. code:: rst
+
+  ==========
+  Main Title
+  ==========
+
+  Subsection
+  ----------
+
+  Sub-subsection
+  ^^^^^^^^^^^^^^
+
+  Paragraph
+  """""""""
+
+
+
+Text decorations
+^^^^^^^^^^^^^^^^
+
+Emphasis and Italics
+
+
+- *Italics*: Use single asterisks
+
+ .. code:: rst
+
+    *italics*
+
+- **Bold**: Use double asterisks.
+
+ .. code:: rst
+
+    **bold**
+
+- ``Monospace``: Use backticks.
+
+ .. code:: rst
+
+    ``monospace``
+
+
+Paragraph
+^^^^^^^^^
+
+Paragraphs are plain texts where indentation matters. Separate paragraphs by leaving a blank line between them.
+
+
+Indentation
+^^^^^^^^^^^
+
+Use spaces instead of tabs. Use hanging indentations where appropriate.
+rST is an indentation sensitive markup language, similar to Python, please maintain consistent indentation (3 spaces) for readability.
+
+
+Line wrapping
+^^^^^^^^^^^^^
+
+Do not hard wrap text, except where necessary (e.g., inside code blocks).
+
+Writing guidelines
+------------------
+
+Correct use of terminology
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Familiarize yourself with the terms defined in the :doc:`glossary </user/reference/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.
+
+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.:
+
+ .. code:: rst
+
+       Open a terminal in dom0 and run:
+
+       .. code:: console
+
+          $ 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:
+
+ .. code:: rst
+
+       Open a terminal in dom0 and run:
+
+       .. code:: console
+
+          # 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.
+
+
+Variable names in commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Syntactically distinguish variables in commands. For example, this is ambiguous:
+
+.. code:: console
+
+     $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
+
+
+
+It should instead be:
+
+.. code:: console
+
+     $ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
+
+
+
+Note that we syntactically distinguish variables in three ways:
+
+1. Surrounding them in angled brackets (``< >``)
+
+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:
+
+- 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.
+
+
+
+Capitalization of "qube"
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+We introduced the term :term:`qube` as a user-friendly alternative to the term :term:`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, :term:`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 orthographically 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.
+
+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 Forum <https://forum.qubes-os.org/docs>`__. 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 Forum <https://forum.qubes-os.org/docs>`__ instead. However, *linking* to external documentation from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum <https://forum.qubes-os.org/>`__ should regularly submit PRs against the documentation index (see :ref:`edit_doc_index`) to add and update Qubes Forum links in the :ref:`“External documentation” <index: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 :doc:`TemplateVM </user/templates/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 :ref:`undergo a review process <developer/general/how-to-edit-the-rst-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.
+
+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.*
+
+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 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
+^^^^^^^^^^^^^^^^^
+
+
+.. code:: rst
+
+     How to Foo
+     ==========
+
+     Fooing is the process by which one foos. There are both general and specific
+     versions of fooing, which vary in usefulness depending on your goals, but for
+     the most part, all fooing is fooing.
+
+     To foo in Qubes 3.2:
+        .. code:: console
+           $ qvm-foo <foo-bar>
+
+     Note that this does not work in Qubes 4.0, where there is a special widget
+     for fooing, which you can find in the lower-right corner of the screen in
+     the Foo Manager. Alternatively, you can use the more general ``qubes-baz``
+     command introduced in 4.0:
+        .. code:: console
+           $ qubes-baz --foo <bar>
+
+     Once you foo, make sure to close the baz before fooing the next bar.
+
+
+
+Correct Example
+^^^^^^^^^^^^^^^
+
+
+.. code:: rst
+
+     Qubes 3.2
+     =========
+
+     How to Foo
+     ----------
+
+     Fooing is the process by which one foos. There are both general and specific
+     versions of fooing, which vary in usefulness depending on your goals, but for
+     the most part, all fooing is fooing.
+
+     To foo:
+
+        .. code:: console
+
+           $ qvm-foo <foo-bar>
+
+     Once you foo, make sure to close the baz before fooing the next bar.
+
+     Qubes 4.0
+     =========
+
+     How to Foo
+     ----------
+
+     Fooing is the process by which one foos. There are both general and specific
+     versions of fooing, which vary in usefulness depending on your goals, but for
+     the most part, all fooing is fooing.
+
+     There is a special widget for fooing, which you can find in the lower-right
+     corner of the screen in the Foo Manager. Alternatively, you can use the
+     general ``qubes-baz`` command:
+
+        .. code:: console
+
+          $ qubes-baz --foo <bar>
+
+     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:
+
+- 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.)
+
+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 :ref:`Git commit message guidelines <developer/code/coding-style:commit message guidelines>`.
+
+
+
+Cheatsheet: Markdown vs. reStructuredText
+-----------------------------------------
+
+For the documentation contributors more familiar with Markdown, here is a small cheatsheet
+highlighting essential differences.
+
+Cheatsheet: Headings
+^^^^^^^^^^^^^^^^^^^^
+
+**Markdown:**
+
+    .. code:: markdown
+
+        # Title
+        ## Section
+        ### Sub-Section
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        =====
+        Title
+        =====
+
+        Section
+        -------
+
+        Seub-Section
+        ^^^^^^^^^^^^
+
+Hyperlinks
+^^^^^^^^^^
+
+External
+
+**Markdown:**
+
+    .. code:: markdown
+
+        [Link Text](http://example.com)
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        `Link Text <http://example.com>`__
+
+Internal
+
+**Markdown:**
+
+    .. code:: markdown
+
+        [Link Text](/doc/some-file)
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        :doc:`Link Text </path/to/file>`
+
+
+For example on cross referencing please see :ref:`cross_referencing`.
+
+Text Decoration
+^^^^^^^^^^^^^^^
+
+**Markdown:**
+
+    .. code:: markdown
+
+        *Italic* or _Italic_
+        **Bold** or __Bold__
+        ~~Strikethrough~~
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        *Italic*
+        **Bold**
+        :strike:`Strikethrough`
+
+Cheatsheet: Lists
+^^^^^^^^^^^^^^^^^
+
+**Markdown:**
+
+    .. code:: markdown
+
+        - Item 1
+        - Item 2
+          - Subitem 1
+          - Subitem 2
+
+        1. Item 1
+        2. Item 2
+           a. Subitem 1
+           b. Subitem 2
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        - Item 1
+        - Item 2
+          - Subitem 1
+          - Subitem 2
+
+        1. Item 1
+        2. Item 2
+           a. Subitem 1
+           b. Subitem 2
+
+Cheatsheet: Tables
+^^^^^^^^^^^^^^^^^^
+
+**Markdown:**
+
+    .. code:: markdown
+
+        | Header 1 | Header 2 |
+        |----------|----------|
+        | Cell 1   | Cell 2   |
+        | Cell 3   | Cell 4   |
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        .. list-table:: rst
+           :widths: 15 10
+           :align: center
+           :header-rows: 1
+
+           * - Header 1
+             - Header 2
+           * - Cell 1
+             - Cell 2
+           * - Cell 3
+             - Cell 4
+
+Cheatsheet: Code Blocks
+^^^^^^^^^^^^^^^^^^^^^^^
+
+**Markdown:**
+    .. code:: markdown
+
+        ```python
+        print("Hello, world!")
+        ```
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        .. code:: python
+
+            print("Hello, world!")
+
+Alerts and Warnings
+^^^^^^^^^^^^^^^^^^^
+
+**Markdown:**
+
+Markdown does not have built-in support for alerts and warnings.
+
+**reStructuredText:**
+
+    .. code:: rst
+
+        .. note::
+
+           This is a note.
+
+        .. warning::
+
+           This is a warning.
+
+        .. danger::
+
+           This is a danger message.

developer/general/usability-ux.rst

@@ -2,19 +2,15 @@
 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 visual style guide <https://www.qubes-os.org/doc/visual-style-guide/>`__ for other design related information.
 
-
 ----
 
-
 Easy To Use
 -----------
 
-
 An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal.
 
 |redx| **Interfaces Should Not**
@@ -27,8 +23,6 @@ An ideal user experience is friendly, and it beckons a new user to explore the i
 
 - Overwhelm the user with too much information and cognitive load
 
-
-
 Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user’s experience, choose a safe and smart default then tuck this setting in an ``Advanced Settings`` panel.
 
 |checkmark| **Interfaces Should**
@@ -41,18 +35,13 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura
 
 - Choose intelligent defaults for settings
 
-
-
 In making software easy to use, it is crucial to be mindful of `cognitive load <https://en.wikipedia.org/wiki/Cognitive_load>`__ which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
 
-
 ----
 
-
 Easy to Understand
 ------------------
 
-
 There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims!
 
 |redx| **Avoid Acronyms**
@@ -67,8 +56,6 @@ Acronyms are compact and make good names for command line tools. They do not mak
 
 - ``NetVM`` - Networking Virtual Machine
 
-
-
 Despite this rule, some acronyms like ``USB`` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms when the full words like ``Universal Serial Bus`` are more likely to confuse users.
 
 |checkmark| **Use Simple Words**
@@ -83,12 +70,8 @@ Use the minimum amount of words needed to be descriptive, but also informative.
 
 - Use ``Networking`` or ``Networking Qube`` instead of ``NetVM`` given context
 
-
-
-
 ----
 
-
 |redx| **Avoid Technical Words**
 
 Technical words are usually more accurate, but they often *only* make sense to technical users and are confusing and unhelpful to non-technical users. Examples of technical words that might show up in Qubes OS are:
@@ -99,8 +82,6 @@ Technical words are usually more accurate, but they often *only* make sense to t
 
 - ``qrexec-daemon``
 
-
-
 These are all terms that have at some point showed up in users’ notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
 
 |checkmark| **Use Common Concepts**
@@ -113,14 +94,10 @@ Large amounts of the global population have been using computers for one or two
 
 - Use ``Qubes`` instead of ``qrexec-daemon`` as it gives better context on what is happening
 
-
-
 These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes).
 
-
 ----
 
-
 |redx| **Avoid Inconsistencies**
 
 It is easy to start abbreviating (or making acronyms) of long terms like ``Disposable Virtual Machine`` depending on where the term shows up in an interface.
@@ -131,8 +108,6 @@ It is easy to start abbreviating (or making acronyms) of long terms like ``Dispo
 
 - ``DisposableVM``
 
-
-
 This variation in terms can cause new users to question or second guess what the three different variations mean, which can lead to inaction or mistakes.
 
 |checkmark| **Make Things Consistent**
@@ -141,14 +116,10 @@ Always strive to keep things consistent in the interfaces as well as documentati
 
 - Use ``Disposable Qube`` at all times as it meets other criteria as well.
 
-
-
 By using the same term throughout an interface, a user can create a mental model and relationship with that term allowing them to feel empowered.
 
-
 ----
 
-
 |redx| **Avoid Duplicate Words**
 
 It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as:
@@ -160,8 +131,6 @@ It is easy to add words like ``Domain`` before items in a list or menu in an att
       - Domain: banking
       - Domain: personal
 
-
-
 The repeated use of the word ``Domain`` requires a user to read it for each item in the list, which makes extra work for the eye in parsing out the relevant word like ``work, banking, or personal``. This also affects horizontal space on fixed width lines.
 
 |checkmark| **Create Groups & Categories**
@@ -175,16 +144,11 @@ It is more efficient to group things under headings instead as this allows the e
       - Banking
       - Personal
 
-
-
-
 ----
 
-
 Easy To Complete
 ----------------
 
-
 Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action.
 
 |redx| **Don’t Leave Users Stranded**
@@ -195,8 +159,6 @@ Consider the following notifications:
 
 - ``There was an error saving Qube "Personal"``
 
-
-
 Instead of displaying solvable errors like these and neglecting to provide a fix:
 
 |checkmark| **Offer Actionable Solutions**
@@ -207,14 +169,10 @@ Error messages and limits such as those in the previous example can be greatly i
 
 - Add a link to a documentation page called ``Troubleshoot saving data``
 
-
-
 In adhering to these principles, you’ll make undesirable situations more manageable for users instead of feeling stranded.
 
-
 ----
 
-
 |checkmark| **Minimize Repetitive Steps**
 
 There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as:
@@ -223,26 +181,18 @@ There are many cases where a user wants to perform an action on more than one fi
 
 2. Navigate through file system
 
+   - Click Folder One
 
+   - Click Folder Two
 
-- Click Folder One
-
-- Click Folder Two
-
-- Click Folder Three
-
-- Click Folder Four
-
+   - Click Folder Three
 
+   - Click Folder Four
 
 3. Select proper file
 
 4. Complete task on file
 
-
-
-
-
 That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process:
 
 1. Click on ``Open File`` from a menu or button
@@ -253,18 +203,13 @@ That subtle act of clicking through a file system can prove to be significant if
 
 4. Complete task
 
-
-
 Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like ``Open Multiple Files`` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do!
 
-
 ----
 
-
 GNOME, KDE, and Xfce
 --------------------
 
-
 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://gtk.org/>`__ rather than Qt for new GUIs.
@@ -277,16 +222,11 @@ All three of these mentioned desktop environments have their own `human interfac
 
 - `Xfce UI Guidlines <https://wiki.xfce.org/dev/hig/general>`__
 
-
-
-
 ----
 
-
 Further Learning & Inspiration
 ------------------------------
 
-
 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 <https://web.archive.org/web/20180101172357/http://learndesignprinciples.com/>`__ by Melissa Mandelbaum
@@ -301,7 +241,5 @@ Learning to make well designing intuitive interfaces and software is specialized
 
 - `Hack Design <https://hackdesign.org/>`__ - online learning program
 
-
-
 .. |checkmark| image:: /attachment/doc/checkmark.png
 .. |redx| image:: /attachment/doc/red_x.png

developer/general/website-style-guide.rst

@@ -0,0 +1,265 @@
+===================
+Website style guide
+===================
+
+
+This page explains the standards we follow for building and maintaining the website. Please follow these guidelines and conventions when modifying the website. For the standards governing the documentation in particular, please see the :doc:`documentation style guide </developer/general/rst-documentation-style-guide>`.
+
+
+Coding conventions
+------------------
+
+The following 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.
+
+General practices
+^^^^^^^^^^^^^^^^^
+
+
+- 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 obscure 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.
+
+Whitespace
+^^^^^^^^^^
+
+- Always use spaces. Never use tabs.
+- Each indentation step should be 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.)
+
+
+Indentation example
+^^^^^^^^^^^^^^^^^^^
+
+Here’s an example that follows the indentation rules:
+
+.. code:: html
+
+      <table>
+        <tr>
+          <th title="Anchor Link"><span class="fa fa-link"></span></th>
+          {% for item in secs.htmlsections[0].columns %}
+            <th>{{ item.title }}</th>
+          {% endfor %}
+        </tr>
+        {% for canary in site.data.sec-canary reversed %}
+          <tr id="{{ canary.canary }}">
+            <td><a href="#{{ canary.canary }}" class="fa fa-link black-icon" title="Anchor link to Qubes Canary row: Qubes Canary #{{ canary.canary }}"></a></td>
+            <td>{{ canary.date }}</td>
+            <td><a href="https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-{{ canary.canary }}-{{ canary.date | date: '%Y' }}.txt">Qubes Canary #{{ canary.canary }}</a></td>
+          </tr>
+        {% endfor %}
+      </table>
+
+
+Markdown style guide and conventions
+------------------------------------
+
+
+*Also see* :doc:`How to edit the website </developer/general/how-to-edit-the-website>`.
+
+Some of the Qubes OS website pages are stored as plain text Markdown files in the `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ repository.
+When making contributions to Markdown files, 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 :code:`[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 ``/donate/`` instead of ``https://www.qubes-os.org/donate/``.
+
+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 <https://www.qubes-os.org/security/qsb/>`__ and `Canaries <https://www.qubes-os.org/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:
+
+- Serving the website offline
+- Website localization
+- Generating offline documentation
+- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror
+
+
+Image linking
+^^^^^^^^^^^^^
+
+To add an image to a page, use the following syntax in the main document.
+
+.. code:: markdown
+
+  [![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png)
+
+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.
+
+HTML and CSS
+^^^^^^^^^^^^
+
+
+Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as :ref:`developer/general/website-style-guide: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.
+
+Use Atx-style syntax for headings: ``##h2``, ``### h3``, etc. Do not use underlining syntax (``-----``).
+
+Indentation
+^^^^^^^^^^^
+
+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.
+
+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.
+
+Line wrapping
+^^^^^^^^^^^^^
+
+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.:
+
+.. code:: markdown
+
+      > **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 :ref:`developer/general/website-style-guide: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.,:
+
+.. code:: markdown
+
+      **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:
+
+.. code:: html
+
+      <div class="alert alert-success" role="alert">
+        <i class="fa fa-check-circle"></i>
+        <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
+        even load any networking drivers, so there is no possibility of
+        internet-based data leaks or attacks during the installation process.
+      </div>
+
+      <div class="alert alert-info" role="alert">
+        <i class="fa fa-info-circle"></i>
+        <b>Note:</b> Using Rufus to create the installation medium means that you <a
+        href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
+        to choose the "Test this media and install Qubes OS" option mentioned in the
+        example below. Instead, choose the "Install Qubes OS" option.
+      </div>
+
+      <div class="alert alert-warning" role="alert">
+        <i class="fa fa-exclamation-circle"></i>
+        <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
+        as a guest hypervisor. In other words, <b>nested virtualization</b> is not
+        supported. In order for a strict compartmentalization to be enforced, Qubes
+        OS needs to be able to manage the hardware directly.
+      </div>
+
+      <div class="alert alert-danger" role="alert">
+        <i class="fa fa-exclamation-triangle"></i>
+        <b>Warning:</b> Qubes has no control over what happens on your computer
+        before you install it. No software can provide security if it is installed on
+        compromised hardware. Do not install Qubes on a computer you don't trust. See
+        [installation security](/doc/install-security/) for more
+        information.
+      </div>
+
+
+
+These render as:
+
+|alerts|
+
+Writing guidelines
+^^^^^^^^^^^^^^^^^^
+
+For writing guidelines please refer to the :ref:`appropriate section <developer/general/rst-documentation-style-guide:writing guidelines>` in the rST documentation style guide
+with the exemption of the following:
+
+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.:
+
+  .. code:: markdown
+
+        Open a terminal in dom0 and run:
+        ```
+        $ 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:
+
+  .. code:: markdown
+
+        Open a terminal in dom0 and run:
+        ```
+        # 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.
+
+
+Git conventions
+---------------
+
+Please follow our :ref:`Git commit message guidelines <developer/code/coding-style:commit message guidelines>`.
+
+.. |alerts| image:: /attachment/doc/website_alerts.png
+   :alt: Depicts different alerts and messages: note, warning, danger and how they are rendered on the website

developer/releases/3_0/release-notes.rst

@@ -3,11 +3,6 @@ Qubes R3.0 release notes
 ========================
 
 
-Qubes R3.0 Release Notes
-------------------------
-
-
-
 
 This Qubes OS release is dedicated to the memory of Caspar Bowden.
 
@@ -43,7 +38,7 @@ Known issues
 
 - If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience “heaviness” with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
 
-- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.0%22+label%3Abug>`__
+- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20milestone%3A%22Release%203.0%22%20type%3ABug>`__
 
 
 

developer/releases/3_0/schedule.rst

@@ -3,8 +3,8 @@ Qubes R3.0 release schedule
 ===========================
 
 
-.. list-table:: 
-   :widths: 11 11 
+.. list-table::
+   :widths: 11 11
    :align: center
    :header-rows: 1
 
@@ -16,5 +16,4 @@ Qubes R3.0 release schedule
      - 3.0-rc3 release
    * - 1 Oct 2015
      - 3.0 release
-   
 

developer/releases/3_1/release-notes.rst

@@ -29,7 +29,7 @@ New features since 3.0
 
 
 
-You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed>`__
+You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20sort%3Aupdated-desc%20milestone%3A%22Release%203.1%22%20label%3A%22release%20notes%22%20is%3Aclosed>`__
 
 Known issues
 ------------
@@ -43,7 +43,7 @@ Known issues
 
 - USB mouse (in the case of USB VM) does not work at first system startup (just after completing firstboot). Workaround: restart the system.
 
-- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.1%22+label%3Abug>`__
+- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20milestone%3A%22Release%203.1%22%20type%3ABug>`__
 
 
 

developer/releases/3_1/schedule.rst

@@ -3,10 +3,10 @@ Qubes R3.1 release schedule
 ===========================
 
 
-This schedule is based on :ref:`Version Scheme <developer/releases/version-scheme:release schedule>`.
+This schedule is based on our :ref:`release-schedule-policy`.
 
-.. list-table:: 
-   :widths: 38 38 
+.. list-table::
+   :widths: 38 38
    :align: center
    :header-rows: 1
 
@@ -24,5 +24,4 @@ This schedule is based on :ref:`Version Scheme <developer/releases/version-schem
      - current-testing freeze before 3.1-rc3
    * -  :strike:`16 Feb 2016`  23 Feb 2016
      - 3.1-rc3 release
-   
 

developer/releases/3_2/release-notes.rst

@@ -25,7 +25,7 @@ New features since 3.1
 
 
 
-You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed>`__
+You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20sort%3Aupdated-desc%20milestone%3A%22Release%203.2%22%20label%3A%22release%20notes%22%20is%3Aclosed>`__
 
 Known issues
 ------------
@@ -37,7 +37,7 @@ Known issues
 
 - Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
 
-- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.2%22+label%3Abug>`__
+- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20milestone%3A%22Release%203.2%22%20type%3ABug>`__
 
 
 

developer/releases/3_2/schedule.rst

@@ -3,10 +3,10 @@ Qubes R3.2 release schedule
 ===========================
 
 
-This schedule is based on :ref:`Version Scheme <developer/releases/version-scheme:release schedule>`.
+This schedule is based on our :ref:`release-schedule-policy`.
 
-.. list-table:: 
-   :widths: 38 38 
+.. list-table::
+   :widths: 38 38
    :align: center
    :header-rows: 1
 
@@ -28,5 +28,3 @@ This schedule is based on :ref:`Version Scheme <developer/releases/version-schem
      - 3.2-rc3 release
    * - 29 Sep 2016
      - 3.2 release
-   
-

developer/releases/4_0/release-notes.rst

@@ -47,7 +47,7 @@ New features since 3.2
 
 
 
-You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed>`__
+You can get detailed description in `completed github issues <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20sort%3Aupdated-desc%20milestone%3A%22Release%204.0%22%20is%3Aclosed%20label%3A%22release%20notes%22>`__
 
 Security Notes
 --------------
@@ -56,6 +56,7 @@ Security Notes
 - PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see `QSB #37 <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt>`__). However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode. These must be set manually.
 
 - The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see `#3737 <https://github.com/QubesOS/qubes-issues/issues/3737>`__).
+
   Steps for dom0 updates:
 
   1. Open the Qubes Menu by clicking on the “Q” icon in the top-left corner of the screen.
@@ -120,7 +121,7 @@ Known issues
 
 - With R4.0.1, which ships kernel-4.19, you may never reach the anaconda startup and be block on an idle black screen with blinking cursor. You can try to add ``plymouth.ignore-serial-consoles`` in the grub installer boot menu right after ``quiet rhgb``. With legacy mode, you can do it directly when booting the DVD or USB key. In UEFI mode, follow the same procedure described for :ref:`disabling <user/troubleshooting/uefi-troubleshooting:installation freezes before displaying installer>` ``nouveau`` module (related `solved issue <https://github.com/QubesOS/qubes-issues/issues/3849>`__ in further version of Qubes).
 
-- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.0%22+label%3Abug>`__
+- For other known issues take a look at `our tickets <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20milestone%3A%22Release%204.0%22%20type%3ABug>`__
 
 
 

developer/releases/4_0/schedule.rst

@@ -3,10 +3,10 @@ Qubes R4.0 release schedule
 ===========================
 
 
-This schedule is based on :ref:`Version Scheme <developer/releases/version-scheme:release schedule>`.
+This schedule is based on our :ref:`release-schedule-policy`.
 
-.. list-table:: 
-   :widths: 88 88 
+.. list-table::
+   :widths: 88 88
    :align: center
    :header-rows: 1
 
@@ -40,5 +40,4 @@ This schedule is based on :ref:`Version Scheme <developer/releases/version-schem
      - decide whether 4.0-rc5 is the final 4.0
    * - 28 Mar 2018
      - final 4.0 release
-   
 

developer/releases/4_1/release-notes.rst

@@ -89,13 +89,13 @@ New features and improvements since Qubes 4.0
 
 
 
-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.1%22+label%3A%22release+notes%22+is%3Aclosed>`__.
+For a full list, including more detailed descriptions, please see `here <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20sort%3Aupdated-desc%20milestone%3A%22Release%204.1%22%20label%3A%22release%20notes%22%20is%3Aclosed>`__.
 
 Known issues
 ------------
 
 
-For a full list of known 4.1 issues with open bug reports, please see `here <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.1%22+label%3A%22T%3A+bug%22>`__. We strongly recommend :doc:`updating Qubes OS </user/how-to-guides/how-to-update>` immediately after installation in order to apply any and all available bug fixes.
+For a full list of known 4.1 issues with open bug reports, please see `here <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen%20is%3Aissue%20milestone%3A%22Release%204.1%22%20type%3ABug>`__. We strongly recommend :doc:`updating Qubes OS </user/how-to-guides/how-to-update>` immediately after installation in order to apply any and all available bug fixes.
 
 Download
 --------

developer/releases/4_1/schedule.rst

@@ -3,10 +3,10 @@ Qubes R4.1 release schedule
 ===========================
 
 
-The table below is based on our :ref:`release schedule policy <developer/releases/version-scheme:release schedule>`.
+The table below is based on our :ref:`release-schedule-policy`.
 
-.. list-table:: 
-   :widths: 10 10 
+.. list-table::
+   :widths: 10 10
    :align: center
    :header-rows: 1
 
@@ -34,5 +34,4 @@ The table below is based on our :ref:`release schedule policy <developer/release
      - decide whether 4.1.0-rc4 is the final 4.1
    * - 2022-02-04
      - final 4.1.0 release
-   
 

developer/releases/4_2/release-notes.rst

@@ -49,7 +49,7 @@ New features and improvements since Qubes 4.1
 
 
 
-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>`__. Below are some screenshots of the new and improved Qubes GUI tools.
+For a full list, including more detailed descriptions, please see `here <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20sort%3Aupdated-desc%20milestone%3A%22Release%204.2%22%20label%3A%22release%20notes%22%20is%3Aclosed>`__. Below are some screenshots of the new and improved Qubes GUI tools.
 
 The new Qubes OS Update tool:
 
@@ -73,7 +73,7 @@ Known issues
 
 
 
-Also see the `full list of open bug reports affecting Qubes 4.2 <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen>`__.
+Also see the `full list of open bug reports affecting Qubes 4.2 <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20label%3Aaffects-4.2%20is%3Aopen%20type%3ABug>`__.
 
 We strongly recommend :doc:`updating Qubes OS </user/how-to-guides/how-to-update>` immediately after installation in order to apply all available bug fixes.
 

developer/releases/4_2/schedule.rst

@@ -2,13 +2,10 @@
 Qubes R4.2 release schedule
 ===========================
 
+The table below is based on our :ref:`release-schedule-policy`.
 
-**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 :ref:`release schedule policy <developer/releases/version-scheme:release schedule>`.
-
-.. list-table:: 
-   :widths: 10 10 
+.. list-table::
+   :widths: 10 10
    :align: center
    :header-rows: 1
 
@@ -22,5 +19,4 @@ The table below is based on our :ref:`release schedule policy <developer/release
      - 4.2.0-rc3 release
    * - 2023-10-13
      - 4.2.0-rc4 release
-   
 

developer/releases/4_3/release-notes.rst

@@ -0,0 +1,344 @@
+==========================
+Qubes OS 4.3 release notes
+==========================
+
+
+Major features and improvements since Qubes 4.2
+===============================================
+
+- Dom0 upgraded to Fedora 41
+  (`#9402 <https://github.com/QubesOS/qubes-issues/issues/9402>`__).
+
+- Xen upgraded to version 4.19
+  (`#9420 <https://github.com/QubesOS/qubes-issues/issues/9420>`__).
+
+- Default Fedora template upgraded to Fedora 42 (Fedora TemplateVMs and
+  StandaloneVMs with version lower than 41 are not supported).
+
+- Default Debian template upgraded to Debian 13 (Debian TemplateVMs and
+  StandaloneVMs with version lower than 12 are not supported).
+
+- Default Whonix templates upgraded to Whonix 18 (Whonix TemplateVMs
+  and StandaloneVMs with version lower than 18 are not supported).
+
+- Preloaded disposables
+  (`#1512 <https://github.com/QubesOS/qubes-issues/issues/1512>`__,
+  `#9907 <https://github.com/QubesOS/qubes-issues/issues/9907>`__,
+  `#9917 <https://github.com/QubesOS/qubes-issues/issues/9917>`__,
+  `#9918 <https://github.com/QubesOS/qubes-issues/issues/9918>`__ &
+  `#10026 <https://github.com/QubesOS/qubes-issues/issues/10026>`__).
+
+- Device “self-identity oriented” assignment (a.k.a New Devices API)
+  (`#9325 <https://github.com/QubesOS/qubes-issues/issues/9325>`__).
+
+- QWT (Qubes Windows Tools) reintroduction with improved features
+  (`#1861 <https://github.com/QubesOS/qubes-issues/issues/1861>`__).
+
+|Screenshot of QWT, Welcome page|
+
+|Screenshot of QWT, Windows 11|
+
+UI/UX
+-----
+
+- New Device UX workflow to allow users easy utilization of new Devices API.
+  A dedicated ``Device Assignments`` page is added to Global Config.
+  Qubes Devices widget is completely redesigned.
+  (`#8537 <https://github.com/QubesOS/qubes-issues/issues/8537>`__).
+
+|Screenshot of Device UX assignments|
+
+|Screenshot of Device UX deny attachment|
+
+|Screenshot of Device UX edit assignment|
+
+|Screenshot of Device UX required devices|
+
+|Screenshot of Device UX Qubes Devices widget|
+
+- New and improved flat icons for GUI tools
+  (`#5657 <https://github.com/QubesOS/qubes-issues/issues/5657>`__).
+
+|Screenshot of Qube Manager|
+
+- The far left icons from the Qube Manager are removed
+  (`#9776 <https://github.com/QubesOS/qubes-issues/issues/9776>`__).
+
+- Application icons are available in VM Settings
+  (`#9829 <https://github.com/QubesOS/qubes-issues/issues/9829>`__).
+
+|Screenshot of Qube Settings Applications|
+
+- Option to add Qubes video Companion to AppMenu
+  (`#9761 <https://github.com/QubesOS/qubes-issues/issues/9761>`__).
+
+- Improved AppMenu navigation with keyboard
+  (`#9006 <https://github.com/QubesOS/qubes-issues/issues/9006>`__).
+
+- Better wording to clarify updater settings and actions
+  (`#8096 <https://github.com/QubesOS/qubes-issues/issues/8096>`__).
+
+- Centralized Tray Notifications
+  (`#889 <https://github.com/QubesOS/qubes-issues/issues/889>`__).
+
+- Option to launch root terminal or console terminal from Qubes Domains widget
+  (`#9788 <https://github.com/QubesOS/qubes-issues/issues/9788>`__)
+
+- Option to open Global Config at a selected section for user
+  convenience
+  (`#9530 <https://github.com/QubesOS/qubes-issues/issues/9530>`__).
+
+- A ``Saving changes...`` dialog is added to Global Config
+  (`#9926 <https://github.com/QubesOS/qubes-issues/issues/9926>`__).
+
+GUI Daemon/Agent improvements
+-----------------------------
+
+- Allowing the GUI Daemon background color to be configurable, mostly
+  useful for people with dark themes
+  (`#9304 <https://github.com/QubesOS/qubes-issues/issues/9304>`__).
+
+- Audio daemon does not connect to recording stream unless recording is
+  explicitly enabled
+  (`#9999 <https://github.com/QubesOS/qubes-issues/issues/9999>`__).
+
+- Legacy X11 App icons (e.g. Xterm) are properly displayed
+  (`#9973 <https://github.com/QubesOS/qubes-issues/issues/9973>`__).
+
+- Labeling virtual pointing device as absolute and not relative
+  (`#228 <https://github.com/QubesOS/qubes-issues/issues/228>`__).
+
+- Improved global clipboard notifications & configurable global clipboard size
+  (`#9296 <https://github.com/QubesOS/qubes-issues/issues/9296>`__ &
+  `#9978 <https://github.com/QubesOS/qubes-issues/issues/9978>`__).
+
+- Supporting Windows qubes in systems with ``sys-gui*``
+  (`#7565 <https://github.com/QubesOS/qubes-issues/issues/7565>`__).
+
+Hardware support improvements
+-----------------------------
+
+- Support for `Advanced Format
+  (AF) <https://en.wikipedia.org/wiki/Advanced_Format>`__ drives better known
+  as 4K sector
+  (`#4974 <https://github.com/QubesOS/qubes-issues/issues/4974>`__).
+
+- Replacing bus/slot/function with full PCI paths for device assignments
+  (`#8681 <https://github.com/QubesOS/qubes-issues/issues/8681>`__
+  & `#8127 <https://github.com/QubesOS/qubes-issues/issues/8127>`__).
+
+- Ability to filter input devices with udev rules.
+  (`#3604 <https://github.com/QubesOS/qubes-issues/issues/3604>`__).
+
+- Fix for graceful rebooting on some (U)EFI systems with buggy firmware
+  (`#6258 <https://github.com/QubesOS/qubes-issues/issues/6258>`__).
+
+- Better support for Bluetooth and external hot-pluggable audio devices
+  with dynamic AudioVM switching
+  (`#7750 <https://github.com/QubesOS/qubes-issues/issues/7750>`__).
+
+Security features
+-----------------
+
+- Templates could request custom kernel command line parameters;
+  currently used for Kicksecure and Whonix templates ``user-sysmaint-split``
+  (`#9750 <https://github.com/QubesOS/qubes-issues/issues/9750>`__).
+
+  - Allow VMs to specify boot modes as being only intended for AppVMs or
+    templates
+    (`#9920 <https://github.com/QubesOS/qubes-issues/issues/9920>`__).
+
+- Shipping GRUB2 from Fedora with all security patches and Bootloader
+  Specification support
+  (`#9471 <https://github.com/QubesOS/qubes-issues/issues/9471>`__).
+
+- SSL client certificate and GPG key support for private template repositories
+  (`#9850 <https://github.com/QubesOS/qubes-issues/issues/9850>`__).
+
+- Preventing unsafe practice of 3rd party template installation with rpm/dnf
+  (`#9943 <https://github.com/QubesOS/qubes-issues/issues/9943>`__).
+
+- Ability to prohibit start of specific qubes
+  (`#9622 <https://github.com/QubesOS/qubes-issues/issues/9622>`__).
+
+- UUID support for qubes and support for addressing them by UUID in policies
+  (`#8862 <https://github.com/QubesOS/qubes-issues/issues/8862>`__ &
+  `#8510 <https://github.com/QubesOS/qubes-issues/issues/8510>`__).
+
+- Custom persist feature to avoid unwanted data to persist as much as possible
+  (`#1006 <https://github.com/QubesOS/qubes-issues/issues/1006>`__).
+
+Anonymity improvements
+----------------------
+
+- Disallowing files, URLs, or any application from Whonix-Workstation
+  qubes to be opened in non-Whonix disposable
+  (`#10051 <https://github.com/QubesOS/qubes-issues/issues/10051>`__).
+
+- Preventing users from changing their Whonix Workstation qubes’ netvm
+  to ``sys-firewall`` (or other clearnet netvms) to avoid IP leaks
+  (`#8551 <https://github.com/QubesOS/qubes-issues/issues/8551>`__).
+
+- kloak: Keystroke-level online anonymization kernel
+  (`#1850 <https://github.com/QubesOS/qubes-issues/issues/1850>`__).
+
+Performance optimizations
+-------------------------
+
+- Option to use volumes directly without snapshots
+  (`#8767 <https://github.com/QubesOS/qubes-issues/issues/8767>`__).
+
+- Retiring ``qubes-rpc-multiplexer`` and directly executing the command from c
+  (`#9062 <https://github.com/QubesOS/qubes-issues/issues/9062>`__).
+
+- Caching "system info" structure for qrexec policy evaluation
+  (`#9362 <https://github.com/QubesOS/qubes-issues/issues/9362>`__).
+
+- Minimal state qubes to make NetVM and USBVM to consume as little RAM as
+  possible.
+
+Updating & upgrading
+--------------------
+
+- Ability to always hide specific TemplateVMs and StandaloneVMs from
+  update tools
+  (`#9029 <https://github.com/QubesOS/qubes-issues/issues/9029>`__).
+
+- pacman hook to notify dom0 about successful manual Archlinux upgrades
+  (`#9233 <https://github.com/QubesOS/qubes-issues/issues/8307>`__),
+
+- Improved R4.2 -> R4.3 upgrade tool
+  (`#9317 <https://github.com/QubesOS/qubes-issues/issues/9317>`__),
+
+  - Using `lvmdevices` feature instead of device filter
+    (`#9421 <https://github.com/QubesOS/qubes-issues/issues/9421>`__).
+
+New/Improved experimental features
+----------------------------------
+
+- Support for Ansible
+  (`#10004 <https://github.com/QubesOS/qubes-issues/issues/10004>`__).
+
+- Support for `Qubes
+  Air <https://www.qubes-os.org/news/2018/01/22/qubes-air/>`__
+  (`#9015 <https://github.com/QubesOS/qubes-issues/issues/9015>`__).
+
+  - qrexec protocol extension to support sending source information to
+    destination
+    (`#9475 <https://github.com/QubesOS/qubes-issues/issues/9475>`__).
+
+- Better support for GUIVM.
+
+  - GUI/Admin domain splitting
+    (`#833 <https://github.com/QubesOS/qubes-issues/issues/833>`__).
+
+  - Automatically removing ‘nomodeset’ boot option when GPU is attached
+    (`#9792 <https://github.com/QubesOS/qubes-issues/issues/9792>`__).
+
+- Initial basic steps to support Wayland session only in GUIVM (but not GUI
+  daemon/agent intra-communication)
+  (`#8515 <https://github.com/QubesOS/qubes-issues/issues/8515>`__ &
+  `#8410 <https://github.com/QubesOS/qubes-issues/issues/8410>`__).
+
+Other
+-----
+
+- Allowing user to add free-form text to qubes (for descriptions, notes,
+  comments, remarks, reminders, etc.)
+  (`#899 <https://github.com/QubesOS/qubes-issues/issues/899>`__).
+
+|Screenshot of Qube Settings Notes|
+
+- Automatically clean up `QubesIncoming` directory if empty
+  (`#8307 <https://github.com/QubesOS/qubes-issues/issues/8307>`__).
+
+- ``vm-config.*`` features to pass external configuration to inside the qube
+  (`#9837 <https://github.com/QubesOS/qubes-issues/issues/9837>`__).
+
+- Admin API for reading/writing denied device-interface list
+  (`#9674 <https://github.com/QubesOS/qubes-issues/issues/9674>`__).
+
+- New Devices API for salt
+  (`#9753 <https://github.com/QubesOS/qubes-issues/issues/9753>`__).
+
+Dropped or replaced features
+----------------------------
+
+- Default screen locker is changed from ``XScreenSaver`` to
+  ``xfce4-screensaver``
+
+- ``Create Qubes VM`` is retired in favor of the improved ``Create New Qube``
+  (`#6561 <https://github.com/QubesOS/qubes-issues/issues/6561>`__).
+
+- Windows 7 support is dropped from QWT.
+
+For a full list, including more detailed descriptions, please see
+`here <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20label%3Atargets-4.3>`__.
+
+Known issues
+============
+
+- Templates restored in 4.3 from a pre-4.3 backup continue to target
+  their original Qubes OS release repos. If you are using fresh
+  templates on a clean 4.3 installation, or if you performed an
+  :ref:`in-place upgrade from 4.2 to 4.3 <user/downloading-installing-upgrading/upgrade/4_3:in-place upgrade>`,
+  then this does not affect you. (For more information, see issue
+  `#8701 <https://github.com/QubesOS/qubes-issues/issues/8701>`__.)
+
+Also see the `full list of open bug reports affecting Qubes
+4.3 <https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20label%3Aaffects-4.3%20is%3Aopen%20type%3ABug>`__.
+
+We strongly recommend :doc:`updating Qubes OS </user/how-to-guides/how-to-update>`
+immediately after installation in order to apply all available bug fixes.
+
+Notes
+=====
+
+- Additional notes for future release candidates will be added here
+
+Download
+========
+
+All Qubes ISOs and associated :doc:`verification files </project-security/verifying-signatures>`
+are available on the `downloads <https://www.qubes-os.org/downloads/>`__ page.
+
+Installation instructions
+=========================
+
+See the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.
+
+Upgrading
+=========
+
+Please see :doc:`how to upgrade to Qubes 4.3 </user/downloading-installing-upgrading/upgrade/4_3>`.
+
+.. |Screenshot of QWT, Welcome page| image:: /attachment/doc/4-3_qwt-hi.png
+   :alt: Windows 11 welcome page after installation in an HVM
+
+.. |Screenshot of QWT, Windows 11| image:: /attachment/doc/4-3_qwt-win11.png
+   :alt: Windows 11 within an HVM qube showing file explorer
+
+.. |Screenshot of Device UX assignments| image:: /attachment/doc/4-3_device-ux-assignments.png
+   :alt: Device Assignments page in Global Config
+
+.. |Screenshot of Device UX deny attachment| image:: /attachment/doc/4-3_device-ux-deny-attachment.png
+   :alt: Deny device attachment config in Global Config
+
+.. |Screenshot of Device UX edit assignment| image:: /attachment/doc/4-3_device-ux-edit-assignment.png
+   :alt: Editing device assignment for a network interface in Global Config
+
+.. |Screenshot of Device UX required devices| image:: /attachment/doc/4-3_device-ux-required-device.png
+   :alt: Editing a required device in Global Config
+
+.. |Screenshot of Device UX Qubes Devices widget| image:: /attachment/doc/4-3_qui-devices.png
+   :alt: Redesigned Qubes Devices widget
+
+.. |Screenshot of Qube Manager| image:: /attachment/doc/4-3_manager.png
+   :alt: Qube Manager with improved flat icons
+
+.. |Screenshot of Qube Settings Applications| image:: /attachment/doc/4-3_vmsettings-applications.png
+   :alt: Qube settings showing icons of Apps
+
+.. |Screenshot of Qube Settings Notes| image:: /attachment/doc/4-3_notes.png
+   :alt: Qube settings showing qube notes
+

developer/releases/4_3/schedule.rst

@@ -0,0 +1,27 @@
+===========================
+Qubes R4.3 release schedule
+===========================
+
+
+.. note::
+
+   This page is still an **unfinished draft in progress**. It is being updated as Qubes 4.3 development and testing continues.
+
+   To get the latest news, check the `news on the main website <https://www.qubes-os.org/news/>`_.
+
+The table below is based on our :ref:`release-schedule-policy`.
+
+.. list-table::
+   :widths: 10 10
+   :align: center
+   :header-rows: 1
+
+   * - Date
+     - Stage
+   * - 2025-08-10
+     - `4.3.0-rc1 release <https://www.qubes-os.org/news/2025/08/10/qubes-os-4-3-0-rc1-available-for-testing/>`_
+   * - 2025-09-19
+     - `4.3.0-rc2 release <https://www.qubes-os.org/news/2025/09/19/qubes-os-4-3-0-rc2-available-for-testing/>`_
+   * - 2025-10-27
+     - `4.3.0-rc3 release <https://www.qubes-os.org/news/2025/10/27/qubes-os-4-3-0-rc3-available-for-testing/>`_
+

developer/releases/notes.rst

@@ -22,4 +22,6 @@ Release notes
 
    Qubes R4.2 release notes </developer/releases/4_2/release-notes>
 
+   Qubes R4.3 release notes </developer/releases/4_3/release-notes>
+
 

developer/releases/schedules.rst

@@ -18,4 +18,6 @@ Release schedules
 
    Qubes R4.2 release schedule </developer/releases/4_2/schedule>
 
+   Qubes R4.3 release schedule </developer/releases/4_3/schedule>
+
 

developer/releases/version-scheme.rst

@@ -29,18 +29,22 @@ When enough progress has been made, we announce the first stable release, e.g. `
 
 Please see :doc:`issue tracking </introduction/issue-tracking>` for information about how releases are handled in the issue tracker.
 
-Release schedule
-----------------
+.. _release-schedule-policy:
+
+Release schedule policy
+-----------------------
 
 
-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.
+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 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.
+Each release candidate period is as follows:
 
-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.
+1. For the first two weeks, **we accept and assign bug reports** to be fixed before the next release candidate.
+2. 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.
+3. 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.
 
-.. list-table:: 
-   :widths: 26 26 
+.. list-table::
+   :widths: 26 26
    :align: center
    :header-rows: 1
 
@@ -52,11 +56,13 @@ The next RC is released five weeks after the former. All packages are published
      - two weeks
    * - ``current-testing`` freeze
      - one week
-   
 
+The next RC is usually **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.
 
 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.
 
+To get a real life example, check the :doc:`4_1/schedule`.
+
 |Release cycle|
 
 Bug priorities
@@ -104,4 +110,4 @@ 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.
 
 .. |Release cycle| image:: /attachment/doc/release-cycle.png
-   
+

developer/services/admin-api.rst

@@ -75,7 +75,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      - ``<class>\n``
-     - 
+     -
    * - ``admin.vm.List``
      - ``dom0|<vm>``
      - `-`
@@ -91,9 +91,11 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.CreateInPool.<class>``
      - ``dom0``
      - template
-     - ``name=<name> label=<label>``, ``pool=<pool> pool:<volume>=<pool>``
+     - | ``name=<name> label=<label>``
+       | ``pool=<pool> pool:<volume>=<pool>``
      - `-`
-     - either use ``pool=`` to put all volumes there, or ``pool:<volume>=`` for individual volumes - both forms are not allowed at the same time
+     - | either use ``pool=`` to put all volumes there,
+       | or ``pool:<volume>=`` for individual volumes - both forms are not allowed at the same time
    * - ``admin.vm.CreateDisposable``
      - template
      - `-`
@@ -130,7 +132,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - ``<label-index>``
      -
-   * - ``admin.label.Remove`` 
+   * - ``admin.label.Remove``
      - ``dom0``
      - label
      - `-`
@@ -146,17 +148,18 @@ it easy to set the policy using current mechanism.
      - ``dom0``
      - property
      - `-`
-     - ``default={True|False}`` ``type={str|int|bool|vm|label|list} <value>``
+     - | ``default={True|False}``
+       | ``type={str|int|bool|vm|label|list} <value>``
      - Type ``list`` is added in R4.1. Values are of type ``str`` and each entry is suffixed with newline character.
    * - ``admin.property.GetAll``
      - ``dom0``
      - `-`
      - `-`
-     - ``<property-name> <full-value-as-in-property.Get>``
+     - ``<property-name> <full-value-as-in-property.Get>\n``
      - Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal ``\n`` and literal ``\`` are encoded as ``\\``.
    * - ``admin.property.GetDefault``
      - ``dom0``
-     - propety
+     - property
      - `-`
      - ``type={str|int|bool|vm|label|list} <value>``
      - Type ``list`` is added in R4.1. Values are of type ``str`` and each entry is suffixed with newline character.
@@ -187,14 +190,15 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.property.List``
      - vm
      - `-`
-     - `-` 
+     - `-`
      - ``<property>\n``
      -
-   * - ``admin.vm.property.Get`` 
+   * - ``admin.vm.property.Get``
      - vm
      - property
      - `-`
-     - ``default={True|False}`` ``type={str|int|bool|vm|label|list} <value>``
+     - | ``default={True|False}``
+       | ``type={str|int|bool|vm|label|list} <value>``
      - Type ``list`` is added in R4.1. Each list entry is suffixed with a newline character.
    * - ``admin.vm.property.GetAll``
      - vm
@@ -223,7 +227,7 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.property.Reset``
      - vm
      - property
-     - `-` 
+     - `-`
      - `-`
      -
    * - ``admin.vm.property.Set``
@@ -262,7 +266,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - value
      -
-   * - ``admin.vm.feature.CheckWithTemplateAndAdminVM``  
+   * - ``admin.vm.feature.CheckWithTemplateAndAdminVM``
      - vm
      - feature
      - `-`
@@ -297,7 +301,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      - ``<tag>\n``
-     - 
+     -
    * - ``admin.vm.tag.Get``
      - vm
      - tag
@@ -318,10 +322,10 @@ it easy to set the policy using current mechanism.
      -
    * - ``admin.vm.firewall.Get``
      - vm
-     - `-` 
+     - `-`
      - `-`
      - ``<rule>\n``
-     - rules syntax as in :doc:`firewall interface </developer/debugging/vm-interface>` (Firewall Rules in 4x) with addition of ``expire=`` and ``comment=`` options; ``comment=`` (if present) must be the last option
+     - rules syntax as in :ref:`firewall interface <developer/debugging/vm-interface:firewall rules in 4.x>` with addition of ``expire=`` and ``comment=`` options; ``comment=`` (if present) must be the last option
    * - ``admin.vm.firewall.Set``
      - vm
      - `-`
@@ -339,13 +343,9 @@ it easy to set the policy using current mechanism.
      - device
      - assignment-serialization
      - `-`
-     -  ``device`` is in form ``<backend-name>+<device-ident>`` optional options given in ``key=value`` format, separated with spaces; options can include ``persistent=True`` to "persistently" attach the device (default is temporary)
-   * - ``admin.vm.device.<class>.Detach``
-     - vm
-     - device
-     - `-`
-     - `-`
-     - ``device`` is in form ``<backend-name>+<device-ident>``
+     - | ``device`` is in form ``<backend-name>+<device-ident>``
+       | optional options given in ``key=value`` format, separated with spaces;
+       | options can include ``persistent=True`` to "persistently" attach the device (default is temporary)
    * - ``admin.vm.device.<class>.Detach``
      - vm
      - device
@@ -355,23 +355,24 @@ it easy to set the policy using current mechanism.
    * - ``admin.vm.device.<class>.Assign``
      - vm
      - device
-     - assignement-serialization
+     - assignment-serialization
      - `-`
-     - ``device`` is in form ``<backend-name>+<device-ident>`` ``assignment-serialization`` is specified in the section Device Serialization.
+     - | ``device`` is in form ``<backend-name>+<device-ident>``
+       | ``assignment-serialization`` is specified in the section Device Serialization.
    * - ``admin.vm.device.<class>.Unassign``
      - vm
      - device
      - `-`
      - `-`
-     - ``device`` is in form ``<backend-name>+<device-ident>`` 
+     - ``device`` is in form ``<backend-name>+<device-ident>``
    * - ``admin.vm.device.<class>.Set.required``
      - vm
      - device
-     - ``True|False``  
+     - ``True|False``
      - `-`
      - ``device`` is in form ``<backend-name>+<device-ident>``
-   * - ``admin.vm.deviceclass.List``
-     - `dom0`
+   * - ``admin.deviceclass.List``
+     - ``dom0``
      - `-`
      - `-`
      - ``<deviceclass>\n``
@@ -381,19 +382,22 @@ it easy to set the policy using current mechanism.
      - device-ident
      - `-`
      - ``<device-ident> <device-serialization>\n``
-     - optional service argument may be used to get info about a single device, ``device-serialization`` is specified in the section Device Serialization.
+     - | optional service argument may be used to get info about a single device,
+       | ``device-serialization`` is specified in the section Device Serialization.
    * - ``admin.vm.device.<class>.Assigned``
      - vm
      - device-ident
      - `-`
      - ``<device-ident> <assignment-serialization>\n``
-     - optional service argument may be used to get info about a single device, ``assignement-serialization`` is specified in the section Device Serialization.
+     - | optional service argument may be used to get info about a single device,
+       | ``assignment-serialization`` is specified in the section Device Serialization.
    * - ``admin.vm.device.<class>.Attached``
      - vm
      - device-ident
      - `-`
      - ``<device-ident> <assignment-serialization>\n``
-     - optional service argument may be used to get info about a single device, ``assignment-serialization`` is specified in the section Device Serialization.
+     - | optional service argument may be used to get info about a single device,
+       | ``assignment-serialization`` is specified in the section Device Serialization.
    * - ``admin.pool.List``
      - ``dom0``
      - `-`
@@ -410,7 +414,7 @@ it easy to set the policy using current mechanism.
      - ``dom0``
      - pool
      - `-`
-     - ``<property>=<value>``
+     - ``<property>=<value>\n``
      -
    * - ``admin.pool.Add``
      - ``dom0``
@@ -430,7 +434,7 @@ it easy to set the policy using current mechanism.
      - `-`
      - `-`
      -
-   * - ``admin.pool.volume.List`` 
+   * - ``admin.pool.volume.List``
      - ``dom0``
      - pool
      - `-`
@@ -483,12 +487,13 @@ it easy to set the policy using current mechanism.
      - pool
      - vid
      - token, to be used in ``admin.pool.volume.CloneTo``
-     - obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails 
+     - | obtain a token to copy volume ``vid`` in ``pool``;
+       | the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails
    * - ``admin.pool.volume.CloneTo``
      - ``dom0``
      - pool
      - ``<vid> <token>``
-     - `-` 
+     - `-`
      - copy volume pointed by a token to volume ``vid`` in ``pool``
    * - ``admin.vm.volume.List``
      - vm
@@ -498,7 +503,7 @@ it easy to set the policy using current mechanism.
      - ``<volume>`` is per-VM volume name (``root``, ``private``, etc), ``<vid>`` is pool-unique volume id
    * - ``admin.vm.volume.Info``
      - vm
-     - volume 
+     - volume
      - `-`
      - ``<property>=<value>\n``
      -
@@ -555,7 +560,8 @@ it easy to set the policy using current mechanism.
      - volume
      - `-`
      - token, to be used in ``admin.vm.volume.CloneTo``
-     - obtain a token to copy ``volume`` of ``vm``; the token is one time use only, it's invalidated by ``admin.vm.volume.CloneTo``, even if the operation fails
+     - | obtain a token to copy ``volume`` of ``vm``;
+       | the token is one time use only, it's invalidated by ``admin.vm.volume.CloneTo``, even if the operation fails
    * - ``admin.vm.volume.CloneTo``
      - vm
      - volume
@@ -566,7 +572,7 @@ it easy to set the policy using current mechanism.
      - vm
      - `-`
      - `-`
-     - ``<state-property>=<value>``
+     - ``<state-property>=<value>\n``
      - state properties: ``power_state``, ``mem``, ``mem_static_max``, ``cputime``
    * - ``admin.vm.Start``
      - vm
@@ -608,7 +614,7 @@ it easy to set the policy using current mechanism.
      - ``dom0``
      - config id
      - `-`
-     - backup info 
+     - backup info
      - info what would be included in the backup
    * - ``admin.backup.Cancel``
      - ``dom0``

developer/services/disposablevm-implementation.rst

@@ -2,73 +2,185 @@
 Disposable implementation
 =========================
 
+.. warning::
 
-**Note: The content below applies to Qubes R3.2.**
+      This page is intended for advanced users.
 
-DisposableVM image preparation
-------------------------------
+Disposable behavior
+-------------------
 
 
-DisposableVM is not started like other VMs, by executing equivalent of ``xl create`` - it would be too slow. Instead, DisposableVM are started by restore from a savefile.
+A :term:`disposable template` is not a disposable in itself, but a special template that can create different :term:`disposable` types, :term:`named disposable <named disposable>` and :term:`unnamed disposables <unnamed disposable>`. This intermediary template serves different functions, first to permit customization of the private volume of a disposable as well as well as a degree of inheritance that would not be possible with normal templates. It has the :py:attr:`template_for_dispvms <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.template_for_dispvms>` property enabled, being a :py:class:`DVMTemplateMixin <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin>`.
 
-Preparing a savefile is done by ``/usr/lib/qubes/qubes_prepare_saved_domain.sh`` script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to “prerun” script. The script executes the following steps:
+A :term:`disposable` is a qube with the :py:class:`DispVM <core-admin:qubes.vm.dispvm.DispVM>` class and is based on a disposable template. Every disposable type has all of its volumes configured to disable :py:attr:`save_on_stop <core-admin:qubes.storage.Volume.save_on_stop>`, therefore no changes are saved on shutdown. Unnamed disposables enables the property :py:attr:`auto_cleanup <core-admin:qubes.vm.dispvm.DispVM.auto_cleanup>` by default, thus automatically removes the qube upon shutdown. Named disposables don't enable :py:attr:`auto_cleanup <core-admin:qubes.vm.dispvm.DispVM.auto_cleanup>` by default, thus the qube skeleton is not removed upon shutdown, thus allowing to keep qube settings.
 
-1. APPVM is started by ``qvm-start``
+Named disposables are useful for service qubes, as referencing static names is easier when the qube name is mentioned on Qrexec policies (:file:`qubes.UpdatesProxy` target) or as a property of another qube, such as a disposable :term:`net qube` which is referenced by downstream clients in the ``netvm`` property.
 
-2. xenstore key ``/local/domain/appvm_domain_id/qubes_save_request`` is created
-
-3. if prerun script was specified, copy it to ``qubes_save_script`` xenstore key
-
-4. wait for the ``qubes_used_mem`` key to appear
-
-5. (in APPVM) APPVM boots normally, up to the point in ``/etc/init.d/qubes_core`` script when the presence of ``qubes_save_request`` key is tested. If it exists, then
-
-   1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
-
-   2. (in APPVM) the amount of used memory is stored to ``qubes_used_mem`` xenstore key
-
-   3. (in APPVM) busy-waiting for ``qubes_restore_complete`` xenstore key to appear
+Unnamed disposables have their names in the format :samp:`disp{1234}`, where :samp:`{1234}` is derived from the :py:attr:`dispid <core-admin:qubes.vm.dispvm.DispVM.dispid>` property, a random integer ranging from 0 to 9999 with a fail-safe mechanism to avoid reusing the same value in a short period.
 
 
+Disposable's creation with Qrexec
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-6. when ``qubes_used_mem`` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
+The system and every qube can have the :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` property. This property can only have disposable template as value or an empty value. If the qube property is set to the default value, it will use the system's property. An exception to the rule is the property of disposables, which always default to their disposables templates to avoid data leaks such as using unintended network paths.
 
-7. APPVM private image is detached
+There are some Qrexec policy rules that have some services with allow resolution in case the target is the :doc:`@dispvm <core-qrexec:qrexec-policy>` tag, which translates to creation of disposables out of the :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` property. It is most commonly used to open files and URLs, (:file:`qubes.OpenInVM` and :file:`qubes.OpenURL`, respectively).
 
-8. the domain is saved via ``xl save``
+It is also possible to write rules that would allow creating disposables out of different disposables templates by using as destination the disposable template name or a tag it has. The destination would be:
 
-9. the COW file volatile.img (cow for root fs and swap) is packed to ``saved_cows.tar`` archive
+- :samp:`@dispvm:{DISPOSABLE_TEMPLATE}`, where :samp:`{DISPOSABLE_TEMPLATE}` is the desired template;
+- :samp:`@dispvm:@tag:{CUSTOM_TAG}`, where :samp:`{CUSTOM_TAG}` is the tag of your choice.
+
+Preloaded disposables
+---------------------
 
 
+The user desires to circumvent any slow process, the creation of disposables fits into this category. Preloaded disposables enables fast retrieval of fresh disposables, so users don't have to get away from the computer or switch tasks when requesting disposables (or not requesting one at all because it was slow).
 
-The ``qubes_prepare_saved_domain.sh`` script is lowlevel. It is usually called by ``qvm-create-default-dvm`` script, that takes care of creating a special AppVM (named template_name-dvm) to be passed to ``qubes_prepare_saved_domain.sh``, as well as copying the savefile to /dev/shm (the latter action is not done if the ``/var/lib/qubes/dvmdata/dont_use_shm`` file exists).
+Preloaded disposables are :term:`unnamed disposables <unnamed disposable>`, it aims to solve the issue of disposable's long startup time by keeping running (powered on and paused) disposable qubes queued. In order to accomplish this, they are started in the background without user interaction, hidden from most graphical applications by being an :term:`internal <internal qube>`. They are unpaused (transparently) when a disposable qube is requested by the user, therefore the user must not worry about the managing the creation or deletion of them, just how many they'd like to have at maximum.
 
-Restoring a DisposableVM from the savefile
-------------------------------------------
+Preloaded disposable's stages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several stages a disposable goes through while preloading and being used. In short:
+
+1. **Preload**: The qube is created and marked as preloaded. Qube is not visible in GUI applications.
+
+  #. **Startup**: Begins qube startup, start basic services in it and attempt to pause.
+
+  #. **Request**: The qube is removed from the preload list. If startup has not yet reached pause, the latter is skipped.
+
+2. **Used**: The qube is marked as used and may be unpaused/resumed (if applicable). Only in this phase, GUI applications treat the qube as any other unnamed disposable and the qube object is returned to the caller if requested.
+
+Preloaded disposable's worry-free life-cycle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-Normally, disposable VM is created when qubes rpc request with target *$dispvm* is received. Then, as a part of rpc connection setup, the ``qfile-daemon-dvm`` program is executed; it executes ``/usr/lib/qubes/qubes_restore`` program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are:
+There are several events that may trigger the creation, deletion of preloaded disposables. If there is a gap between the current number of preloaded disposables and the maximum number allowed, it will be capped *event*\ ually (refill), if the qube is at an invalid state, it will be deleted or replaced (refresh) as soon as possible.
 
-1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
+We cannot prevent all gaps at the moment it occurs and users should not be responsible for filling them, the system must manage to fill gaps when possible.
 
-2. restore the COW files from the ``saved_cows.tar``
-
-3. create the ``/var/run/qubes/fast_block_attach`` file, whose presence tells the ``/etc/xen/scripts/block`` script to bypass some redundant checks and execute as fast as possible.
-
-4. execute ``xl restore`` in order to restore a domain.
-
-5. create the same xenstore keys as normally created when AppVM boots (e.g. ``qubes_ip``)
-
-6. create the ``qubes_restore_complete`` xenstore key. This allows the boot process in DisposableVM to continue.
+Preloaded disposable's management
+"""""""""""""""""""""""""""""""""
 
 
+These are common events that trigger changes in preloaded disposables quantity:
 
-The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.
+- Refill or remove:
+  - Changing the ``preload-dispvm-max`` feature;
+  - Changing system's :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` while system's feature is set to a different value than the disposable template setting;
+- Refill:
+  - (Re)starting :file:`qubes-preload-dispvm.service`;
+  - Using a preloaded disposable;
+  - Requesting a disposable;
+- Refresh:
+  - Updating the volumes of a template or disposable template;
+  - Qubesd was interrupted mid preload creation, on the next service restart, :py:meth:`domain-load <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.on_domain_loaded>` of the disposable template.
 
-Validating the DisposableVM savefile
-------------------------------------
+Preloaded disposable's temporary gaps
+"""""""""""""""""""""""""""""""""""""
 
 
-DisposableVM savefile contains references to template rootfs and to COW files. The COW files are restored before each DisposableVM start, so they cannot change. On the other hand, if templateVM is started, the template rootfs will change, and it may not be coherent with the COW files.
+Some rarer events that may cause a gap in preloaded disposables temporarily:
 
-Therefore, the check for template rootfs modification time being older than DisposableVM savefile modification time is required. It is done in ``qfilexchgd`` daemon, just before restoring DisposableVM. If necessary, an attempt is made to recreate the DisposableVM savefile, using the last template used (or default template, if run for the first time) and the default prerun script, residing at ``/var/lib/qubes/vm-templates/templatename/dispvm_prerun.sh``. Unfortunately, the prerun script takes a lot of time to execute - therefore, after template rootfs modification, the next DisposableVM creation can be longer by about 2.5 minutes.
+- There is not enough memory to preload at the moment, won't create the qube; and
+- Service to check if the system is fully operational has failed and will remove the qube. Should not attempt refill as it most likely would lead to the same outcome to infinity.
+
+Preloaded disposable's bootstrap
+""""""""""""""""""""""""""""""""
+
+
+To bootstrap the creation of preloaded disposables after boot, the service :file:`qubes-preload-dispvm.service` is used instead of :py:meth:`domain-load <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.on_domain_loaded>` of the disposable template because it relies on systemd to:
+
+- Order this action after the autostart or standard qubes, they must precede in order to have a functional system;
+- Skip preloading if kernel command line prevents autostart.
+
+Preloaded disposable's memory management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+At the end of preloading, it attempts to manage memory of the qube right before pause, because it is not possible to negotiate memory with the domain after pause. It attempts to retrieve memory from the qube on :py:meth:`domain-pre-paused <core-admin:qubes.vm.dispvm.DispVM.on_domain_pre_paused>` by setting it to use its preferred memory value. In :doc:`qmemman terms </developer/services/qmemman>`, preferred memory is just enough to have the qube running.
+
+This process can take a bit of time because it depends on how fast the qube can free up memory. In ``qubes.qmemman.systemstate``, there is a timeout (``CHECK_PERIOD``) and a threshold in transfer speed (``CHECK_MB_S``) when attempting to balloon, then, when both of these conditions are met, the memory management seizes and the preloaded disposable is paused.
+
+Although it takes some time, increasing the preload creation stage, we do not worry much about it because it economizes memory on the long run, the biggest problems is that qmemman is synchronous, so only one request can be made at a time, anything that takes too much time on qmemman could prevent ballooning/balancing of other qubes on the system.
+
+Preloaded disposable's pause
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Preloaded disposables are paused for various reasons:
+
+- Detection if the qube was used without being requested with :py:meth:`core-admin:qubes.vm.dispvm.DispVM.from_appvm`. Not every communication with a qube goes through :program:`qubesd`, it may go via Qrexec or GUI daemon;
+- CPU scheduling economy, domain is not eligible; and
+- Cronjob, timers and other things that don't block the init system and service manager completion won't run, they could possibly alter a clean state.
+
+But this comes at a cost:
+
+- Memory management before pause may take some seconds, that is not prejudicial to the time to use the qube but it is prejudicial to the system as :doc:`qmemman </developer/services/qmemman>` can not balloon/balance other qubes in the mean time due to its design.
+
+Preloaded disposable's security
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+As preloaded disposables are started before being used, methods to prevent accidental tampering have been put in place as well as guarantees to prevent reuse:
+
+- The qube has the ``internal`` feature enabled, Qubes GUI applications were patched to hide and show :term:`internal qubes<internal qube>` by handling events for ``domain-feature-((pre-)?set|delete):internal``;
+- When requesting an unnamed disposable, the qube object is only returned to the user once it has finished preloading;
+- The qube is paused as the last stage of preloading, this permits receiving :py:meth:`domain-unpaused <core-admin:qubes.vm.dispvm.DispVM.on_domain_unpaused>` event and be notified that the qube was used, marked as such and removed from the preload list to avoid reuse, even without the qube being requested with :py:meth:`core-admin:qubes.vm.dispvm.DispVM.from_appvm`;
+- The GUID and Audio daemon only connects to the GUI agent and audio agent on the qube after the preloaded disposable is marked as used, this prevents that an autostarted applications appearing on the screen before it is ready or before pause, which could be confusing. Enabling a GUI is controlled by the :py:attr:`is_preload <core-admin:qubes.vm.dispvm.DispVM.is_preload>` property, that when disabled, allows the GUI and audio connection to initiate.
+
+Another point of security is reliability:
+
+- The ``preload-dispvm-threshold`` feature controls how much free memory must be present on the system before attempting to create a new preloaded disposable. Used to ensure preloaded disposables do not consume all available memory, which would prevent starting other qubes.
+
+To have late GUI daemon but an early GUI agent, changes have been made that limit the usability on ``sys-gui``. `Events such as plugging or removing external monitors can't work, it will be ignored by Xephyr <https://github.com/QubesOS/qubes-gui-agent-linux/pull/253>`__.
+
+Alternatives considered
+^^^^^^^^^^^^^^^^^^^^^^^
+
+
+For an alternative to be considered for implementation, it must meet the following requirements:
+
+- No memory or ``vcpus`` restrictions such as limiting to a few number of ``vcpus`` or assigns memory on request (can be slow).
+- Performant as much as a normal disposable even on long running sessions;
+- Caller transparency, no change necessary for callers, the request must be transparent and the server must find the fastest option. This is to avoid transition burden (API breakage).
+
+From the evaluated options, only :ref:`preload queue <developer/services/disposablevm-implementation:preload queue>` meets all requirements.
+
+
+Restoration from savefile
+"""""""""""""""""""""""""
+
+
+**Description**: Disposable template booted, its image was dumped (suspend to disk), newly disposables would restore this image to become their own.
+
+**Evaluation**:
+
+- Used in R3.2, worked at that time, when there was only one disposable template available, see next points of why it can't be used anymore.
+- Incompatible with multiple ``vcpus``.
+- Some memory issues.
+- Savefile creation takes a long time. The disposable qube savefile contains references to template rootfs and :abbr:`CoW (Copy-on-Write)` files, if there is a modification on the template or disposable template, it took longer than 2.5 minutes to generate the next disposable.
+
+Xen domain fork
+"""""""""""""""
+
+
+**Description**: domain forking is the process of creating a domain with an empty memory space and a parent domain specified from which to populate the memory when necessary. For the new domain to be functional the domain state is copied over as part of the fork operation (HVM params, heap allocation etc). This description was sourced from `[Xen-devel] [RFC PATCH for-next 17/18] xen/mem_sharing: VM forking, Tamas K Lengyel <https://lists.xenproject.org/archives/html/xen-devel/2019-09/msg02497.html>`__.
+
+**Evaluation**:
+
+- Shares too much information from the trunk to the forks. This appears to have improved if not totally fixed on Linux 6.14, as mentioned by Andrew Cooper on Qubes OS Summit 2025;
+- Requires changing properties after the fork is done, this includes, but not limited to, ``xid`` of connected qubes, network uplink;
+- Not designed for long running sessions, the initial intention was fuzzing. As fast as the creation can be, the usage may be slower as memory is mapped on request. Xen doesn't have a poper :abbr:`CoW (Copy-on-Write)` support for domain memory, so making a full copy of a domain on fork also has some overhead;
+- Tamas K Lengyiel `VM Forking & Hypervisor-Based Fuzzing with Xen <https://www.youtube.com/watch?v=3MYo8ctD_aU>`__ presentation during the Open Source Summit Europe in 2022, showed impressive results on CPU i5-8350U, an average of time of 0.745 ms per fork (created 1300 VM/s). These fast results were later explained that was due to not initializing the whole VM memory on the fork unless it was requested, as explained on the point above. Still impressive results but current usage is limited to fuzzing.
+
+Preload queue
+"""""""""""""
+
+
+**Description**: Start disposables and queue them in a disposable template feature, unnamed disposables requested will prefer to retrieve disposables from this list.
+
+**Evaluation**:
+
+- Because the qube is running prior to being requested, multiple components have to be patched to support it to various levels off difficulty. Excluding from backups to allowing removal of disposable templates that only have preloaded disposables to even stranger issues such as deferring net qube change from a preloaded disposable where the old net qube has already been purged from the system.
+- The biggest difference between the queue and the other alternatives is that this solution works, is reliable and fulfills all requirements. A proper solution would be patching upstream Xen to implement :abbr:`CoW (Copy-on-Write)`, but that would involve a lot more work than what the Qubes Team can provide with current resources.