diff --git a/.gitignore b/.gitignore index e35d8850..1ce958af 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ _build +**/__pycache__/* +uv.lock +poetry.lock +.venv diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9a52b135..526e0844 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -21,5 +21,6 @@ python: formats: - pdf - epub +- htmlzip diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e2bd856..d249e0aa 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 0ab67025..a1443f0e 100644 --- a/README.md +++ b/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). diff --git a/_dev/index.rst b/_dev/index.rst index cc737d8a..d2ef552b 100644 --- a/_dev/index.rst +++ b/_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 + core-admin-client + qubes-core-qrexec - - - core-admin-client <> -.. _core-admin-client: /projects/core-admin-client - - - - - -Or see the main Qubes OS documentation -.. _the main qubes os documentation: https://www.qubes-os.org/doc/ - -. +Or see `the main Qubes OS documentation `_. diff --git a/attachment/doc/4-3_device-ux-assignments.png b/attachment/doc/4-3_device-ux-assignments.png new file mode 100644 index 00000000..793e2f91 Binary files /dev/null and b/attachment/doc/4-3_device-ux-assignments.png differ diff --git a/attachment/doc/4-3_device-ux-deny-attachment.png b/attachment/doc/4-3_device-ux-deny-attachment.png new file mode 100644 index 00000000..67122a84 Binary files /dev/null and b/attachment/doc/4-3_device-ux-deny-attachment.png differ diff --git a/attachment/doc/4-3_device-ux-edit-assignment.png b/attachment/doc/4-3_device-ux-edit-assignment.png new file mode 100644 index 00000000..c27936f0 Binary files /dev/null and b/attachment/doc/4-3_device-ux-edit-assignment.png differ diff --git a/attachment/doc/4-3_device-ux-required-device.png b/attachment/doc/4-3_device-ux-required-device.png new file mode 100644 index 00000000..fece4cf6 Binary files /dev/null and b/attachment/doc/4-3_device-ux-required-device.png differ diff --git a/attachment/doc/4-3_manager.png b/attachment/doc/4-3_manager.png new file mode 100644 index 00000000..5a17c9f9 Binary files /dev/null and b/attachment/doc/4-3_manager.png differ diff --git a/attachment/doc/4-3_notes.png b/attachment/doc/4-3_notes.png new file mode 100644 index 00000000..caf3b4df Binary files /dev/null and b/attachment/doc/4-3_notes.png differ diff --git a/attachment/doc/4-3_qui-devices.png b/attachment/doc/4-3_qui-devices.png new file mode 100644 index 00000000..222fb03d Binary files /dev/null and b/attachment/doc/4-3_qui-devices.png differ diff --git a/attachment/doc/4-3_qwt-hi.png b/attachment/doc/4-3_qwt-hi.png new file mode 100644 index 00000000..52e2b872 Binary files /dev/null and b/attachment/doc/4-3_qwt-hi.png differ diff --git a/attachment/doc/4-3_qwt-win11.png b/attachment/doc/4-3_qwt-win11.png new file mode 100644 index 00000000..87f801bd Binary files /dev/null and b/attachment/doc/4-3_qwt-win11.png differ diff --git a/attachment/doc/4-3_vmsettings-applications.png b/attachment/doc/4-3_vmsettings-applications.png new file mode 100644 index 00000000..43e0ef40 Binary files /dev/null and b/attachment/doc/4-3_vmsettings-applications.png differ diff --git a/attachment/doc/QWT_install_select.png b/attachment/doc/QWT_install_select.png index 39001d97..f57dbd89 100644 Binary files a/attachment/doc/QWT_install_select.png and b/attachment/doc/QWT_install_select.png differ diff --git a/attachment/doc/QWT_no_PV_network.png b/attachment/doc/QWT_no_PV_network.png index 6999cbf3..e2b15879 100644 Binary files a/attachment/doc/QWT_no_PV_network.png and b/attachment/doc/QWT_no_PV_network.png differ diff --git a/attachment/doc/doc-pr_01_page-source-button-rtd.png b/attachment/doc/doc-pr_01_page-source-button-rtd.png new file mode 100644 index 00000000..7cca1d0e Binary files /dev/null and b/attachment/doc/doc-pr_01_page-source-button-rtd.png differ diff --git a/attachment/doc/doc-pr_02_github-edit-rst.png b/attachment/doc/doc-pr_02_github-edit-rst.png new file mode 100644 index 00000000..14d77888 Binary files /dev/null and b/attachment/doc/doc-pr_02_github-edit-rst.png differ diff --git a/attachment/doc/doc-pr_03_sign-in-rst.png b/attachment/doc/doc-pr_03_sign-in-rst.png new file mode 100644 index 00000000..74167734 Binary files /dev/null and b/attachment/doc/doc-pr_03_sign-in-rst.png differ diff --git a/attachment/doc/doc-pr_04_fork-rst1.png b/attachment/doc/doc-pr_04_fork-rst1.png new file mode 100644 index 00000000..062821a5 Binary files /dev/null and b/attachment/doc/doc-pr_04_fork-rst1.png differ diff --git a/attachment/doc/doc-pr_04_fork-rst2.png b/attachment/doc/doc-pr_04_fork-rst2.png new file mode 100644 index 00000000..c15a4eef Binary files /dev/null and b/attachment/doc/doc-pr_04_fork-rst2.png differ diff --git a/attachment/doc/doc-pr_04_fork-rst3.png b/attachment/doc/doc-pr_04_fork-rst3.png new file mode 100644 index 00000000..4a6fc192 Binary files /dev/null and b/attachment/doc/doc-pr_04_fork-rst3.png differ diff --git a/attachment/doc/doc-pr_05_edit-rst.png b/attachment/doc/doc-pr_05_edit-rst.png new file mode 100644 index 00000000..97b631ad Binary files /dev/null and b/attachment/doc/doc-pr_05_edit-rst.png differ diff --git a/attachment/doc/doc-pr_06_commit-msg-rst.png b/attachment/doc/doc-pr_06_commit-msg-rst.png new file mode 100644 index 00000000..c894bcbc Binary files /dev/null and b/attachment/doc/doc-pr_06_commit-msg-rst.png differ diff --git a/attachment/doc/doc-pr_09_create-pr-rst.png b/attachment/doc/doc-pr_09_create-pr-rst.png new file mode 100644 index 00000000..66396e12 Binary files /dev/null and b/attachment/doc/doc-pr_09_create-pr-rst.png differ diff --git a/attachment/doc/doc-pr_10_view-pr-rtd.png b/attachment/doc/doc-pr_10_view-pr-rtd.png new file mode 100644 index 00000000..1ceabc00 Binary files /dev/null and b/attachment/doc/doc-pr_10_view-pr-rtd.png differ diff --git a/attachment/doc/doc-pr_11_view-pr-rtd.png b/attachment/doc/doc-pr_11_view-pr-rtd.png new file mode 100644 index 00000000..ea42d9b3 Binary files /dev/null and b/attachment/doc/doc-pr_11_view-pr-rtd.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png new file mode 100644 index 00000000..27ecf049 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-disposable-fail.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png new file mode 100644 index 00000000..ca22d6a9 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png b/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png new file mode 100644 index 00000000..9b7a1d7f Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/personal-settings-allow-fullscreen.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png b/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png new file mode 100644 index 00000000..5566bdd7 Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/qubes-global-config-allow-fullscreen.png differ diff --git a/attachment/doc/how-to-enter-fullscreen-mode/windows-seamless-1.png b/attachment/doc/how-to-enter-fullscreen-mode/windows-seamless-1.png new file mode 100644 index 00000000..0477ff4d Binary files /dev/null and b/attachment/doc/how-to-enter-fullscreen-mode/windows-seamless-1.png differ diff --git a/attachment/doc/howto-screenshot-1.png b/attachment/doc/howto-screenshot-1.png new file mode 100644 index 00000000..538796a6 Binary files /dev/null and b/attachment/doc/howto-screenshot-1.png differ diff --git a/attachment/doc/howto-screenshot-2.png b/attachment/doc/howto-screenshot-2.png new file mode 100644 index 00000000..f46b8000 Binary files /dev/null and b/attachment/doc/howto-screenshot-2.png differ diff --git a/attachment/doc/howto-screenshot-3.png b/attachment/doc/howto-screenshot-3.png new file mode 100644 index 00000000..94d142e6 Binary files /dev/null and b/attachment/doc/howto-screenshot-3.png differ diff --git a/attachment/doc/media-removable.png b/attachment/doc/media-removable.png deleted file mode 100644 index 1a9c1f6f..00000000 Binary files a/attachment/doc/media-removable.png and /dev/null differ diff --git a/attachment/doc/qubes-devices.svg b/attachment/doc/qubes-devices.svg new file mode 100644 index 00000000..b55c7b01 --- /dev/null +++ b/attachment/doc/qubes-devices.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/attachment/doc/r4.0-open-in-dispvm-1.png b/attachment/doc/r4.0-open-in-dispvm-1.png deleted file mode 100644 index 1c9f77c5..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-1.png and /dev/null differ diff --git a/attachment/doc/r4.0-open-in-dispvm-2.png b/attachment/doc/r4.0-open-in-dispvm-2.png deleted file mode 100644 index 3b61fe0b..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-2.png and /dev/null differ diff --git a/attachment/doc/r4.0-open-in-dispvm-3.png b/attachment/doc/r4.0-open-in-dispvm-3.png deleted file mode 100644 index 8a5123ac..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-3.png and /dev/null differ diff --git a/attachment/doc/r4.1-converting-pdf.png b/attachment/doc/r4.1-converting-pdf.png old mode 100755 new mode 100644 diff --git a/attachment/doc/r4.1-dom0-appmenu-select.png b/attachment/doc/r4.1-dom0-appmenu-select.png old mode 100755 new mode 100644 diff --git a/attachment/doc/r4.1-snapshot_40.png b/attachment/doc/r4.1-snapshot_40.png old mode 100755 new mode 100644 diff --git a/attachment/doc/r4.3-disp-default-global.png b/attachment/doc/r4.3-disp-default-global.png new file mode 100644 index 00000000..ab75231a Binary files /dev/null and b/attachment/doc/r4.3-disp-default-global.png differ diff --git a/attachment/doc/r4.3-disp-default-local.png b/attachment/doc/r4.3-disp-default-local.png new file mode 100644 index 00000000..66097b8c Binary files /dev/null and b/attachment/doc/r4.3-disp-default-local.png differ diff --git a/attachment/doc/r4.3-disp-preload-global.png b/attachment/doc/r4.3-disp-preload-global.png new file mode 100644 index 00000000..837f8a28 Binary files /dev/null and b/attachment/doc/r4.3-disp-preload-global.png differ diff --git a/attachment/doc/r4.3-disp-preload-local.png b/attachment/doc/r4.3-disp-preload-local.png new file mode 100644 index 00000000..09618048 Binary files /dev/null and b/attachment/doc/r4.3-disp-preload-local.png differ diff --git a/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png b/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png new file mode 100644 index 00000000..2cc1be91 Binary files /dev/null and b/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png differ diff --git a/attachment/doc/r4.3-dom0-menu-disp-firefox.png b/attachment/doc/r4.3-dom0-menu-disp-firefox.png new file mode 100644 index 00000000..eebd1f57 Binary files /dev/null and b/attachment/doc/r4.3-dom0-menu-disp-firefox.png differ diff --git a/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png new file mode 100644 index 00000000..e66f67b0 Binary files /dev/null and b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png differ diff --git a/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png new file mode 100644 index 00000000..8819e341 Binary files /dev/null and b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png differ diff --git a/attachment/doc/rst-rtd-epub-pdf.png b/attachment/doc/rst-rtd-epub-pdf.png new file mode 100644 index 00000000..8ef1e211 Binary files /dev/null and b/attachment/doc/rst-rtd-epub-pdf.png differ diff --git a/attachment/doc/rst-rtd-workflow.png b/attachment/doc/rst-rtd-workflow.png new file mode 100644 index 00000000..b3de558b Binary files /dev/null and b/attachment/doc/rst-rtd-workflow.png differ diff --git a/attachment/doc/website_alerts.png b/attachment/doc/website_alerts.png new file mode 100644 index 00000000..4893b829 Binary files /dev/null and b/attachment/doc/website_alerts.png differ diff --git a/attachment/doc/website_hcl.png b/attachment/doc/website_hcl.png new file mode 100644 index 00000000..815a385d Binary files /dev/null and b/attachment/doc/website_hcl.png differ diff --git a/attachment/doc/website_news_section.png b/attachment/doc/website_news_section.png new file mode 100644 index 00000000..36fbaf6b Binary files /dev/null and b/attachment/doc/website_news_section.png differ diff --git a/attachment/doc/windows-seamless-1.png b/attachment/doc/windows-seamless-1.png index 21066d29..0477ff4d 100644 Binary files a/attachment/doc/windows-seamless-1.png and b/attachment/doc/windows-seamless-1.png differ diff --git a/attachment/doc/windows-seamless-4.png b/attachment/doc/windows-seamless-4.png index a2104a27..8e8ba89e 100644 Binary files a/attachment/doc/windows-seamless-4.png and b/attachment/doc/windows-seamless-4.png differ diff --git a/attachment/doc/windows-seamless-7.png b/attachment/doc/windows-seamless-7.png index afd5ee75..0dcb1af4 100644 Binary files a/attachment/doc/windows-seamless-7.png and b/attachment/doc/windows-seamless-7.png differ diff --git a/attachment/icons/128x128/apps/qubes-logo-icon.png b/attachment/icons/128x128/apps/qubes-logo-icon.png new file mode 100644 index 00000000..98f6036e Binary files /dev/null and b/attachment/icons/128x128/apps/qubes-logo-icon.png differ diff --git a/attachment/icons/favicon-16x16.png b/attachment/icons/favicon-16x16.png new file mode 100644 index 00000000..c26853d5 Binary files /dev/null and b/attachment/icons/favicon-16x16.png differ diff --git a/conf.py b/conf.py index 0c6a5f90..d4e4eebe 100644 --- a/conf.py +++ b/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 diff --git a/developer/building/qubes-builder-details.rst b/developer/building/qubes-builder-details.rst index 90ff6207..ce5c9e9f 100644 --- a/developer/building/qubes-builder-details.rst +++ b/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 `__ . This can be used for building Qubes R4.1 and later, and all related components. Components Makefile.builder file diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst index 6b547f0f..30c441e6 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/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 `__. @@ -10,40 +9,29 @@ For details and customization, use `Qubes OS v2 builder documentation ` to the project, there are two ways. Whichever method you choose, you must :doc:`sign your code ` before it can be accepted. - **Preferred**: Use GitHub’s `fork & pull requests `__. + 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 ` in order to notify people who do not receive GitHub notifications. - Send a patch to the :ref:`qubes-devel mailing list ` (``git format-patch``). diff --git a/developer/debugging/test-bench.rst b/developer/debugging/test-bench.rst index 47f69d00..4a64cc20 100644 --- a/developer/debugging/test-bench.rst +++ b/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 diff --git a/developer/debugging/vm-interface.rst b/developer/debugging/vm-interface.rst index 7864d6c8..87523cc8 100644 --- a/developer/debugging/vm-interface.rst +++ b/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 diff --git a/developer/debugging/windows-debugging.rst b/developer/debugging/windows-debugging.rst index ce219540..dd0d0471 100644 --- a/developer/debugging/windows-debugging.rst +++ b/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 `__ 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 ` 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: diff --git a/developer/general/developing-gui-applications.rst b/developer/general/developing-gui-applications.rst index 4eb42d60..00d237aa 100644 --- a/developer/general/developing-gui-applications.rst +++ b/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 --------------- diff --git a/developer/general/gsod.rst b/developer/general/gsod.rst index 7230be65..1b2e9645 100644 --- a/developer/general/gsod.rst +++ b/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 `) 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 ` -- Review `issues `__ containing common troubleshooting steps (checking specific logs etc) +- Review `issues `__ 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 `__ +- `reStructuredText `__ @@ -284,7 +276,7 @@ Improve Getting Started page - basic Qubes OS knowledge -- `Markdown `__ +- `reStructuredText `__ @@ -310,7 +302,7 @@ Rewrite qrexec documentation **Knowledge prerequisite**: -- `Markdown `__ +- `reStructuredText `__ diff --git a/developer/general/how-to-edit-the-rst-documentation.rst b/developer/general/how-to-edit-the-rst-documentation.rst new file mode 100644 index 00000000..fbafc380 --- /dev/null +++ b/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) `__ files in +the `qubes-doc `__ repository. + +We use `Sphinx `__ for building and +`Read The Docs (RTD) `__ for hosting. +RTD is a `continuous‑documentation deployment platform `__ 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 `__ 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 `__: + +.. 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 `__, +a dedicated Git repository hosted on `GitHub `__. 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 ` 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 ` 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 `. + +(**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 `__ +the `qubes-doc `__ repo, make your changes, +then `submit a pull request `__. +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 `__. + +|pull-request-confirm| + +If any of your changes should be reflected in the :doc:`documentation index (a.k.a. table of contents) ` — 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 `__, +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--.org.readthedocs.build/en//``. + + +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) ` is +`index.rst `__. + + +:file:`index.rst` contains information about the hierarchy between the files in the documentation and/or +the connection between them. `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 `__ in the directory `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 + + +If you want to add a caption to the image, you may do so using the optional ``caption`` of the `figure directive `__. +Another way without a caption is to use the `image directive `__. + +Then, add your image(s) in a the :file:`attachment/doc` folder in the `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 `__ as in + +.. code-block:: rst + + how to :doc:`contribute code ` do [...] + +When referencing to a section in an existing rST file use the ``:ref:`` `role `__ as in + +.. code-block:: rst + + See the :ref:`USB Troubleshooting guide ` 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 `. + +which will point to :ref:`this section `. + +.. code:: rst + + we :ref:`distrust the infrastructure ` + +which will refer to :ref:`this section `. + + +For further options and use cases please refer to `Cross-references `__. + + +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 `__. +It contains settings and extensions that define how the documentation will be generated. +You can find it `here `__. + +You can also find a :file:`readthedocs.yml` `file `__ +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 `__ +as defined in :file:`conf.py`, as well a simple custom one to embed YouTube videos, +which can be found `here `__. + + +.. _build_locally: + +Building the rST documentation locally +====================================== + + +In order to build the Qubes OS rST documentation locally clone the `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 `__, +`poetry `__ or `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 `__ if you wish. + +Creating a Python environment with poetry +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +1. `Install poetry `__ 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 `__. + + .. 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 `__ 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? ` + +All pull requests (PRs) against `qubes-doc `__ must pass review +prior to be merged, except in the case of :ref:`external documentation ` +(see `#4693 `__). This +process is designed to ensure that contributed text is accurate and +non-malicious. This process is a best effort that should provide a +reasonable degree of assurance, but it is not foolproof. For example, +all text characters are checked for ANSI escape sequences. However, +binaries, such as images, are simply checked to ensure they appear or +function the way they should when the website is rendered. They are not +further analyzed in an attempt to determine whether they are malicious. + +Once a pull request passes review, the reviewer should add a signed +comment stating, “Passed review as of ```` (or similar). +The documentation maintainer then verifies that the pull request is +mechanically sound (no merge conflicts, broken links, ANSI escapes, +etc.). If so, the documentation maintainer then merges the pull request, +adds a PGP-signed tag to the latest commit (usually the merge commit), +then pushes to the remote. In cases in which another reviewer is not +required, the documentation maintainer may review the pull request (in +which case no signed comment is necessary, since it would be redundant +with the signed tag). + +Questions, problems, and improvements +===================================== + +If you have a question about something you read in the documentation or +about how to edit the documentation, please post it on the `forum `__ +or send it to the appropriate :doc:`mailing list `. If you see that something in the +documentation should be fixed or improved, please +:ref:`contribute ` the change yourself. To +report an issue with the documentation, please follow our standard +:doc:`issue reporting guidelines `. (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 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 on RTD diff --git a/developer/general/how-to-edit-the-website.rst b/developer/general/how-to-edit-the-website.rst new file mode 100644 index 00000000..37c96862 --- /dev/null +++ b/developer/general/how-to-edit-the-website.rst @@ -0,0 +1,220 @@ +======================= +How to edit the website +======================= + + +*Also see the* :doc:`Website style guide `. + +The Qubes OS website content is stored in the `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 `__. +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 `. + +How to submit a pull request +---------------------------- + +We keep all relevant files in `qubesos.github.io `__, as well as +`qubes-attachment `__, +`qubes-hcl `__ and `qubes-posts `__ - dedicated Git repositories +hosted on `GitHub `__. + +A few notes to consider: + +- Since Qubes is a security-oriented project, every change will be :ref:`reviewed ` 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 `. +- 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 ` 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 `__ but would be beneficial to the Qubes community, please consider adding it to the :doc:`documentation ` or the :ref:`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 ` with the documentation. + +The Qubes OS website +-------------------- + +The Qubes OS site is generated with `Jekyll `__, 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 `__, as well as its submodules: +- `qubes-attachment `__, +- `qubes-hcl `__ and +- `qubes-posts `__. + + +The contents of the `qubes-posts `__ repository is reflected in the `News section `__: + +|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 `__ repository can be seen in the `Hardware Compatibility List (HCL) table `__: + +|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 ` at any time. + +The `qubes-attachment `__ 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 `__ 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 `__ 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 `__) 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 `__ 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 // + +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 `__) + - 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 `__ 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 `__. + +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? ` + +All pull requests (PRs) against `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 ````" (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 `__ or send it to the appropriate :doc:`mailing list `. If you see that something in the website should be fixed or improved, please :ref:`contribute ` the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines `. (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 diff --git a/developer/general/package-contributions.rst b/developer/general/package-contributions.rst index 0ea46f52..55ffb9a0 100644 --- a/developer/general/package-contributions.rst +++ b/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 `. 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 `__. @@ -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 `__ 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 `__ organization on GitHub as public recognition of your contribution (but without push access; see `Review Procedure <#review-procedure>`__), and `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 `__ organization on GitHub as public recognition of your contribution (but without push access; see :ref:`developer/general/package-contributions:review procedure`), and `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 ` (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 ` 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. diff --git a/developer/general/research.rst b/developer/general/research.rst index 3dde880a..af465532 100644 --- a/developer/general/research.rst +++ b/developer/general/research.rst @@ -8,7 +8,7 @@ posts related to Qubes OS. Secure Software Development =========================== -- `Security challenges for the Qubes build process `__ by Joanna Rutkowska, May 2016 +- `Security challenges for the Qubes build process `__ by Joanna Rutkowska, May 2016 Towards Trusted Hardware diff --git a/developer/general/rst-documentation-style-guide.rst b/developer/general/rst-documentation-style-guide.rst new file mode 100644 index 00000000..7aefbfaf --- /dev/null +++ b/developer/general/rst-documentation-style-guide.rst @@ -0,0 +1,937 @@ +=========================================== +reStructuredText documentation style guide +=========================================== + +*Also see* :doc:`How to edit the documentation `. + +This page explains the standards we follow for writing, formatting, and organizing the documentation. +Please follow these guidelines and conventions when editing the rST documentation. +For the standards governing the website (as opposed to the rST documentation hosted on `https://doc.qubes-os.org `__), +please see the :doc:`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 `. + +reStructuredText conventions +---------------------------- + +All the documentation is written in `reStructuredText (rST) `__. When making contributions, please observe the following style conventions. +If you’re not familiar with reStructuredText syntax, `the Sphinx primer `__ +is a great resource, as well as `this quick reStructuredText `__. +Please always be mindful that rST syntax is sensitive to indentation! + + +Directives +^^^^^^^^^^ + +A `directive `__ is a generic block of explicit markup, +provided by `Docutils `__ and extended by `Sphinx `__. +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 `__ 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 `__ 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 `__ 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 `__ +or `code-block `__. + +By specifying the language, you enable pygments, which show syntax color coding for that code sample (see `here `__ 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 `__ 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 `__. + +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 `__ 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 `__. + +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:*** Using Rufus to create the installation medium means that you + `wont be able `__ + 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 `__ + 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 `__ +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 `__ 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 `__ and +`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 `__ +- the ``:guilabel:`` `role `__ +- the ``:menuselection:`` `role `__ +- the ``:samp:`` `role `__ +- the ``:kbd:`` `role `__ + +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 `. + +- 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? ` + +- 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 ` +* :doc:`core-admin-client ` +* :doc:`core-qrexec ` + +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 `__ 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 `__ + +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 ` text + +instead of: + +.. code:: rst + + text `contribute code ` 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 `__ and `Canaries `__), 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 `__ 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 `. 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 `__. 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= --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 `__, mainly in `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 `__. External documentation should not be submitted to `qubes-doc `__. If you’ve written a piece of documentation that is not appropriate for `qubes-doc `__, we encourage you to submit it to the `Qubes Forum `__ instead. However, *linking* to external documentation from `qubes-doc `__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum `__ 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” ` 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 `. 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 ` 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 `__ for more background information. + + +Release-specific documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +*See* `#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 + + 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 + + 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 + + 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 + + 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 `__. + +Git conventions +--------------- + + +Please follow our :ref:`Git 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 `__ + +Internal + +**Markdown:** + + .. code:: markdown + + [Link Text](/doc/some-file) + +**reStructuredText:** + + .. code:: rst + + :doc:`Link Text ` + + +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. diff --git a/developer/general/usability-ux.rst b/developer/general/usability-ux.rst index 593de59b..c3f9515e 100644 --- a/developer/general/usability-ux.rst +++ b/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 `__ 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 `__ 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 `__ and `Xfce `__. We are currently migrating towards using `GNOME `__. 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 `__ 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 `__ - - - ---- - 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 `__ by Melissa Mandelbaum @@ -301,7 +241,5 @@ Learning to make well designing intuitive interfaces and software is specialized - `Hack Design `__ - online learning program - - .. |checkmark| image:: /attachment/doc/checkmark.png .. |redx| image:: /attachment/doc/red_x.png diff --git a/developer/general/website-style-guide.rst b/developer/general/website-style-guide.rst new file mode 100644 index 00000000..3e6c923d --- /dev/null +++ b/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 `. + + +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)! `__ 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 + + + + + {% for item in secs.htmlsections[0].columns %} + + {% endfor %} + + {% for canary in site.data.sec-canary reversed %} + + + + + + {% endfor %} +
{{ item.title }}
{{ canary.date }}Qubes Canary #{{ canary.canary }}
+ + +Markdown style guide and conventions +------------------------------------ + + +*Also see* :doc:`How to edit the website `. + +Some of the Qubes OS website pages are stored as plain text Markdown files in the `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 `__ 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 `__ and `Canaries `__), 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 `__ 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 `__ where possible (see `here `__ 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 `__, 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 `__ 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 + + + + + + + + + + + +These render as: + +|alerts| + +Writing guidelines +^^^^^^^^^^^^^^^^^^ + +For writing guidelines please refer to the :ref:`appropriate section ` 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 `. + +.. |alerts| image:: /attachment/doc/website_alerts.png + :alt: Depicts different alerts and messages: note, warning, danger and how they are rendered on the website diff --git a/developer/releases/3_0/release-notes.rst b/developer/releases/3_0/release-notes.rst index f8aaed7f..f3772de8 100644 --- a/developer/releases/3_0/release-notes.rst +++ b/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 `__ +- For other known issues take a look at `our tickets `__ diff --git a/developer/releases/3_0/schedule.rst b/developer/releases/3_0/schedule.rst index cc6a55a7..db58b504 100644 --- a/developer/releases/3_0/schedule.rst +++ b/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 - diff --git a/developer/releases/3_1/release-notes.rst b/developer/releases/3_1/release-notes.rst index ca9cee6c..8f99d285 100644 --- a/developer/releases/3_1/release-notes.rst +++ b/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 `__ +You can get detailed description in `completed github issues `__ 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 `__ +- For other known issues take a look at `our tickets `__ diff --git a/developer/releases/3_1/schedule.rst b/developer/releases/3_1/schedule.rst index 970caed7..63592e1d 100644 --- a/developer/releases/3_1/schedule.rst +++ b/developer/releases/3_1/schedule.rst @@ -3,10 +3,10 @@ Qubes R3.1 release schedule =========================== -This schedule is based on :ref:`Version Scheme `. +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 `__ +You can get detailed description in `completed github issues `__ 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 `__ +- For other known issues take a look at `our tickets `__ diff --git a/developer/releases/3_2/schedule.rst b/developer/releases/3_2/schedule.rst index fc367c20..8bb58562 100644 --- a/developer/releases/3_2/schedule.rst +++ b/developer/releases/3_2/schedule.rst @@ -3,10 +3,10 @@ Qubes R3.2 release schedule =========================== -This schedule is based on :ref:`Version Scheme `. +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 `__ +You can get detailed description in `completed github issues `__ 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 `__). 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 `__). + 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 ` ``nouveau`` module (related `solved issue `__ in further version of Qubes). -- For other known issues take a look at `our tickets `__ +- For other known issues take a look at `our tickets `__ diff --git a/developer/releases/4_0/schedule.rst b/developer/releases/4_0/schedule.rst index 6a1ed551..9f0a6a88 100644 --- a/developer/releases/4_0/schedule.rst +++ b/developer/releases/4_0/schedule.rst @@ -3,10 +3,10 @@ Qubes R4.0 release schedule =========================== -This schedule is based on :ref:`Version Scheme `. +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 `__. +For a full list, including more detailed descriptions, please see `here `__. Known issues ------------ -For a full list of known 4.1 issues with open bug reports, please see `here `__. We strongly recommend :doc:`updating Qubes OS ` 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 `__. We strongly recommend :doc:`updating Qubes OS ` immediately after installation in order to apply any and all available bug fixes. Download -------- diff --git a/developer/releases/4_1/schedule.rst b/developer/releases/4_1/schedule.rst index 7982acb3..2a56afd0 100644 --- a/developer/releases/4_1/schedule.rst +++ b/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 `. +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 `__. Below are some screenshots of the new and improved Qubes GUI tools. +For a full list, including more detailed descriptions, please see `here `__. 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 `__. +Also see the `full list of open bug reports affecting Qubes 4.2 `__. We strongly recommend :doc:`updating Qubes OS ` immediately after installation in order to apply all available bug fixes. diff --git a/developer/releases/4_2/schedule.rst b/developer/releases/4_2/schedule.rst index 85a1bb9a..63c2dea0 100644 --- a/developer/releases/4_2/schedule.rst +++ b/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 `. - -.. 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 `__). + +- Xen upgraded to version 4.19 + (`#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 `__, + `#9907 `__, + `#9917 `__, + `#9918 `__ & + `#10026 `__). + +- Device “self-identity oriented” assignment (a.k.a New Devices API) + (`#9325 `__). + +- QWT (Qubes Windows Tools) reintroduction with improved features + (`#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 `__). + +|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 `__). + +|Screenshot of Qube Manager| + +- The far left icons from the Qube Manager are removed + (`#9776 `__). + +- Application icons are available in VM Settings + (`#9829 `__). + +|Screenshot of Qube Settings Applications| + +- Option to add Qubes video Companion to AppMenu + (`#9761 `__). + +- Improved AppMenu navigation with keyboard + (`#9006 `__). + +- Better wording to clarify updater settings and actions + (`#8096 `__). + +- Centralized Tray Notifications + (`#889 `__). + +- Option to launch root terminal or console terminal from Qubes Domains widget + (`#9788 `__) + +- Option to open Global Config at a selected section for user + convenience + (`#9530 `__). + +- A ``Saving changes...`` dialog is added to Global Config + (`#9926 `__). + +GUI Daemon/Agent improvements +----------------------------- + +- Allowing the GUI Daemon background color to be configurable, mostly + useful for people with dark themes + (`#9304 `__). + +- Audio daemon does not connect to recording stream unless recording is + explicitly enabled + (`#9999 `__). + +- Legacy X11 App icons (e.g. Xterm) are properly displayed + (`#9973 `__). + +- Labeling virtual pointing device as absolute and not relative + (`#228 `__). + +- Improved global clipboard notifications & configurable global clipboard size + (`#9296 `__ & + `#9978 `__). + +- Supporting Windows qubes in systems with ``sys-gui*`` + (`#7565 `__). + +Hardware support improvements +----------------------------- + +- Support for `Advanced Format + (AF) `__ drives better known + as 4K sector + (`#4974 `__). + +- Replacing bus/slot/function with full PCI paths for device assignments + (`#8681 `__ + & `#8127 `__). + +- Ability to filter input devices with udev rules. + (`#3604 `__). + +- Fix for graceful rebooting on some (U)EFI systems with buggy firmware + (`#6258 `__). + +- Better support for Bluetooth and external hot-pluggable audio devices + with dynamic AudioVM switching + (`#7750 `__). + +Security features +----------------- + +- Templates could request custom kernel command line parameters; + currently used for Kicksecure and Whonix templates ``user-sysmaint-split`` + (`#9750 `__). + + - Allow VMs to specify boot modes as being only intended for AppVMs or + templates + (`#9920 `__). + +- Shipping GRUB2 from Fedora with all security patches and Bootloader + Specification support + (`#9471 `__). + +- SSL client certificate and GPG key support for private template repositories + (`#9850 `__). + +- Preventing unsafe practice of 3rd party template installation with rpm/dnf + (`#9943 `__). + +- Ability to prohibit start of specific qubes + (`#9622 `__). + +- UUID support for qubes and support for addressing them by UUID in policies + (`#8862 `__ & + `#8510 `__). + +- Custom persist feature to avoid unwanted data to persist as much as possible + (`#1006 `__). + +Anonymity improvements +---------------------- + +- Disallowing files, URLs, or any application from Whonix-Workstation + qubes to be opened in non-Whonix disposable + (`#10051 `__). + +- Preventing users from changing their Whonix Workstation qubes’ netvm + to ``sys-firewall`` (or other clearnet netvms) to avoid IP leaks + (`#8551 `__). + +- kloak: Keystroke-level online anonymization kernel + (`#1850 `__). + +Performance optimizations +------------------------- + +- Option to use volumes directly without snapshots + (`#8767 `__). + +- Retiring ``qubes-rpc-multiplexer`` and directly executing the command from c + (`#9062 `__). + +- Caching "system info" structure for qrexec policy evaluation + (`#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 `__). + +- pacman hook to notify dom0 about successful manual Archlinux upgrades + (`#9233 `__), + +- Improved R4.2 -> R4.3 upgrade tool + (`#9317 `__), + + - Using `lvmdevices` feature instead of device filter + (`#9421 `__). + +New/Improved experimental features +---------------------------------- + +- Support for Ansible + (`#10004 `__). + +- Support for `Qubes + Air `__ + (`#9015 `__). + + - qrexec protocol extension to support sending source information to + destination + (`#9475 `__). + +- Better support for GUIVM. + + - GUI/Admin domain splitting + (`#833 `__). + + - Automatically removing ‘nomodeset’ boot option when GPU is attached + (`#9792 `__). + +- Initial basic steps to support Wayland session only in GUIVM (but not GUI + daemon/agent intra-communication) + (`#8515 `__ & + `#8410 `__). + +Other +----- + +- Allowing user to add free-form text to qubes (for descriptions, notes, + comments, remarks, reminders, etc.) + (`#899 `__). + +|Screenshot of Qube Settings Notes| + +- Automatically clean up `QubesIncoming` directory if empty + (`#8307 `__). + +- ``vm-config.*`` features to pass external configuration to inside the qube + (`#9837 `__). + +- Admin API for reading/writing denied device-interface list + (`#9674 `__). + +- New Devices API for salt + (`#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 `__). + +- Windows 7 support is dropped from QWT. + +For a full list, including more detailed descriptions, please see +`here `__. + +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 `, + then this does not affect you. (For more information, see issue + `#8701 `__.) + +Also see the `full list of open bug reports affecting Qubes +4.3 `__. + +We strongly recommend :doc:`updating Qubes OS ` +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 ` +are available on the `downloads `__ page. + +Installation instructions +========================= + +See the :doc:`installation guide `. + +Upgrading +========= + +Please see :doc:`how to upgrade to Qubes 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 + diff --git a/developer/releases/4_3/schedule.rst b/developer/releases/4_3/schedule.rst new file mode 100644 index 00000000..0e34a9f9 --- /dev/null +++ b/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 `_. + +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 `_ + * - 2025-09-19 + - `4.3.0-rc2 release `_ + * - 2025-10-27 + - `4.3.0-rc3 release `_ + diff --git a/developer/releases/notes.rst b/developer/releases/notes.rst index bbea04f7..9657223d 100644 --- a/developer/releases/notes.rst +++ b/developer/releases/notes.rst @@ -22,4 +22,6 @@ Release notes Qubes R4.2 release notes + Qubes R4.3 release notes + diff --git a/developer/releases/schedules.rst b/developer/releases/schedules.rst index 8c3fe7c1..6eb15237 100644 --- a/developer/releases/schedules.rst +++ b/developer/releases/schedules.rst @@ -18,4 +18,6 @@ Release schedules Qubes R4.2 release schedule + Qubes R4.3 release schedule + diff --git a/developer/releases/version-scheme.rst b/developer/releases/version-scheme.rst index 0ef58164..25122d6d 100644 --- a/developer/releases/version-scheme.rst +++ b/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 ` 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 - + diff --git a/developer/services/admin-api.rst b/developer/services/admin-api.rst index 03964deb..30cb17a7 100644 --- a/developer/services/admin-api.rst +++ b/developer/services/admin-api.rst @@ -75,7 +75,7 @@ it easy to set the policy using current mechanism. - `-` - `-` - ``\n`` - - + - * - ``admin.vm.List`` - ``dom0|`` - `-` @@ -91,9 +91,11 @@ it easy to set the policy using current mechanism. * - ``admin.vm.CreateInPool.`` - ``dom0`` - template - - ``name= label=