merge upstream and add rst version of the how to edit Markdown and Markdown and website style guide docs

introduction/contributing.rst

@@ -23,7 +23,7 @@ Thank you for your interest in contributing to Qubes! Here are some of the many
 
 - Create `artwork <https://github.com/QubesOS/qubes-artwork>`__ (plymouth themes, installer themes, wallpapers, etc.)
 
-- `Write and edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__
+- :doc:`Write and edit the documentation </developer/general/how-to-edit-the-documentation>`
 
 - `Donate <https://www.qubes-os.org/donate/>`__ to the project
 

introduction/faq.rst

@@ -320,7 +320,7 @@ Should I trust this website?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone `review <https://www.qubes-os.org/doc/how-to-edit-the-documentation/#security>`__), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was `intentionally written in Markdown so as to be readable as plain text for this very reason <https://www.qubes-os.org/doc/documentation-style-guide/#markdown-conventions>`__. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
+This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :ref:`review <developer/general/how-to-edit-the-documentation:security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason <developer/general/documentation-style-guide:markdown conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
 
 
 What does it mean to "distrust the infrastructure"?
@@ -563,10 +563,10 @@ or
 
   .. code:: bash
 
-        echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
-        MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
-        MOD=`modprobe -R $MODALIAS | head -n 1`
-        echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
+        $ echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
+        $ MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
+        $ MOD=`modprobe -R $MODALIAS | head -n 1`
+        $ echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
 
 
 
@@ -692,7 +692,7 @@ From a ``dom0`` prompt, enter:
 
 .. code:: bash
 
-      qvm-prefs <HVMname> kernel ""
+      $ qvm-prefs <HVMname> kernel ""
 
 
 

introduction/getting-started.rst

@@ -9,13 +9,13 @@ The Basics
 ----------
 
 
-Qubes OS is an operating system built out of securely-isolated compartments, or :ref:`qubes <user/reference/glossary:qube>`. You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. You can have as many qubes as you want! Most of the time, you’ll be using an :ref:`app qube <user/reference/glossary:app qube>`, a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a :ref:`template <user/reference/glossary:template>`. The same template can be a base for various qubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is successful, the damage is limited to a single qube.
+Qubes OS is an operating system built out of securely-isolated compartments, or :term:`qubes <qube>`. You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. You can have as many qubes as you want! Most of the time, you’ll be using an :term:`app qube`, a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a :term:`template`. The same template can be a base for various qubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is successful, the damage is limited to a single qube.
 
 Suppose you want to use your favorite web browser in several different qubes. You’d install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only have to install the web browser a single time, and updating the template updates all the qubes based on it. This elegant design saves time and space while enhancing security.
 
-There are also some “helper” qubes in your system. Each qube that connects to the Internet does so through a network-providing :ref:`service qube <user/reference/glossary:service qube>`. If you need to access USB devices, another service qube will do that. There’s also a :ref:`management qube <user/reference/glossary:management qube>` that automatically handles a lot of background housekeeping. For the most part, you won’t have to worry about it, but it’s nice to know that it’s there. As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a `Linux distribution <https://en.wikipedia.org/wiki/Linux_distribution>`__) and corresponding version number. There are many ready-to-use :doc:`templates </user/templates/templates>` to choose from, and you can download and have as many as you like.
+There are also some “helper” qubes in your system. Each qube that connects to the Internet does so through a network-providing :term:`service qube`. If you need to access USB devices, another service qube will do that. There’s also a :term:`management qube` that automatically handles a lot of background housekeeping. For the most part, you won’t have to worry about it, but it’s nice to know that it’s there. As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a `Linux distribution <https://en.wikipedia.org/wiki/Linux_distribution>`__) and corresponding version number. There are many ready-to-use :doc:`templates </user/templates/templates>` to choose from, and you can download and have as many as you like.
 
-Last but not least, there’s a very special :ref:`admin qube <user/reference/glossary:admin qube>` used to administer your entire system. There’s only one admin qube, and it’s called :ref:`dom0 <user/reference/glossary:dom0>`. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be “game over”- an effective compromise of the entire system. That’s why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn’t happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the `desktop environment <https://en.wikipedia.org/wiki/Desktop_environment>`__ and `window manager <https://en.wikipedia.org/wiki/Window_manager>`__. Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That’s what your app qubes are for!) In short, be very careful when interacting with dom0.
+Last but not least, there’s a very special :term:`admin qube` used to administer your entire system. There’s only one admin qube, and it’s called :term:`dom0`. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be “game over”- an effective compromise of the entire system. That’s why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn’t happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the `desktop environment <https://en.wikipedia.org/wiki/Desktop_environment>`__ and `window manager <https://en.wikipedia.org/wiki/Window_manager>`__. Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That’s what your app qubes are for!) In short, be very careful when interacting with dom0.
 
 Color & Security
 ^^^^^^^^^^^^^^^^
@@ -189,7 +189,7 @@ Documentation
 -------------
 
 
-Browse our extensive library of :doc:`documentation </index>` for users and developers of Qubes OS. You can even `help us improve it <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__!
+Browse our extensive library of :doc:`documentation </index>` for users and developers of Qubes OS. You can even :doc:`help us improve it </developer/general/how-to-edit-the-documentation>`!
 
 .. |snapshot_41.png| image:: /attachment/doc/r4.1-snapshot_40.png
    

introduction/intro.rst

@@ -1,3 +1,8 @@
+:og:image: https://doc.qubes-os.org/en/latest/_images/qubes-trust-level-architecture.png
+:og:image:alt: An overview of the security features of Qubes OS, including strong isolation, templating system,...
+:og:image:width: 778
+:og:image:height: 591
+
 ============
 Introduction
 ============
@@ -6,11 +11,11 @@ What is Qubes OS?
 -----------------
 
 Qubes OS is a free and open-source, security-oriented operating system for
-single-user desktop computing. Qubes OS leverages `Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :ref:`qubes <user/reference/glossary:qube>`.
+single-user desktop computing. Qubes OS `leverages Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :term:`qubes <qube>`.
 
 
-These qubes, which are implemented as :ref:`virtual machines (VMs)<user/reference/glossary:vm>`, have specific:
-
+These qubes, which are implemented as :term:`virtual machines (VMs) <vm>`, have specific:
+               
 - **Purposes:** with a predefined set of one or many isolated
   applications, for personal or professional projects, to manage the
   :doc:`network stack </developer/system/networking>`, :doc:`the firewall </user/security-in-qubes/firewall>`, or to fulfill other
@@ -20,7 +25,7 @@ These qubes, which are implemented as :ref:`virtual machines (VMs)<user/referenc
   :doc:`stripped-down </introduction/getting-started/>` virtual machines based on popular operating systems,
   such as :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__.
-
+               
 - **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with
   :doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
 
@@ -39,7 +44,7 @@ Features
 - **Strong isolation** Isolate different pieces of software as if they were installed on separate
   physical machines using advanced virtualization techniques.
 
-- **Template system** Use :ref:`app qubes <user/reference/glossary:app qube>` to
+- **Template system** Use :term:`app qubes  <app qube>` to
   share a root file system without sacrificing security using the innovative
   :doc:`Template system </user/templates/templates>`.
 
@@ -47,7 +52,7 @@ Features
 - **Multiple operating systems** Use multiple operating systems at the same time, including
   :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__
-
+         
 - **Disposables** Create :doc:`disposables </user/how-to-guides/how-to-use-disposables>` on the fly that self-destruct when shut down.
 
 - **Whonix integration** Run `Tor <https://www.torproject.org/>`__ securely system-wide using `Whonix with Qubes <https://www.whonix.org/wiki/Qubes>`__.
@@ -137,7 +142,7 @@ plug in devices, and install software free from worry. It's a place where
 **you** have control over your software, not the other way around.
 (See some :doc:`examples of how different types of users organize their qubes </user/how-to-guides/how-to-organize-your-qubes>`.)
 
-Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__,
+Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__, 
 `Mullvad <https://twitter.com/mullvadnet/status/631010362083643392>`__,
 and `Let's Encrypt <https://twitter.com/letsencrypt/status/1239934557710737410>`__
 rely on Qubes as they build and maintain critical privacy and
@@ -187,7 +192,7 @@ presentation.
 
 
 - If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
-- If you’re a developer, there’s dedicated :ref:`developer documentation <index:developer documentation>` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
-- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.
+- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
+- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :ref:`Installation guide`.
 - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum </introduction/support>`.
 

introduction/issue-tracking.rst

@@ -21,7 +21,7 @@ I see something that should be changed in the documentation.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-We encourage you to submit the change yourself! Please see the `how to edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__ for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
+We encourage you to submit the change yourself! Please see the :doc:`how to edit the documentation </developer/general/how-to-edit-the-documentation>` for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
 
 I would like to report a security vulnerability.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -47,13 +47,15 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure
 
 6. Do not delete the provided issue template. Fill out every applicable section.
 
-7. Make sure to mention any relevant documentation and other issues you’ve already seen. We don’t know what you’ve seen unless you tell us. If you don’t list it, we’ll assume you haven’t seen it.
+7. Please note that AIs often `hallucinate <https://en.wikipedia.org/wiki/Hallucination_(artificial_intelligence)>`__ about Qubes OS. If you're using an AI to assist you, please check its conclusions against the `official documentation <https://doc.qubes-os.org/>`__.
 
-8. If any sections of the issue template are *truly* not applicable, you may remove them.
+8. Make sure to mention any relevant documentation and other issues you’ve already seen. We don’t know what you’ve seen unless you tell us. If you don’t list it, we’ll assume you haven’t seen it.
 
-9. Submit your issue.
+9. If any sections of the issue template are *truly* not applicable, you may remove them.
 
-10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information.
+10. Submit your issue.
+
+11. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information.
 
 
 
@@ -171,18 +173,23 @@ If your issue is not actionable, please see :doc:`Help, Support, Mailing Lists,
 
 This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see `the issue tracker is not a discussion forum <#the-issue-tracker-is-not-a-discussion-forum>`__).
 
-New issues should not be duplicates of existing issues
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Before you submit an issue, check to see whether it has already been reported. Search through the existing issues – both open and closed – by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. The Qubes team will see your comment and reopen the issue, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don’t have anything to add but still want to receive email updates, you can click the “Subscribe” button at the side or bottom of the comments.
-
 Every issue must be of a single type
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 Every issue must be exactly one of the following types: a bug report (``bug``), a feature or improvement request (``enhancement``), or a task (``task``). Do not file multi-typed issues. Instead, file multiple issues of distinct types. The Qubes team will classify your issue according to its type.
 
+New issues should not be duplicates of existing issues
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Before you submit an issue, check to see whether it has already been reported. Search through the existing issues – both open and closed – by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it.
+
+For bug reports, if you find an issue that is the same as or subsumes yours, leave a comment on the existing bug report issue rather than opening a new one, even if the existing bug report is closed. If a bug report affects more than one Qubes version, we usually keep only one bug report for all versions. The Qubes team will see your comment and reopen the bug report, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don’t have anything to add but still want to receive email updates, you can click the “Subscribe” button at the side or bottom of the comments.
+
+For feature requests, it depends on what you want to report. If the initial implementation was incomplete or unsuccessful, then please leave a comment on the existing feature request issue, and we will reopen it. However, if the initial implementation of the feature was successful, and you are reporting a problem with the feature that arose later, then please open a separate bug report (if one doesn't already exist for that bug) instead of commenting on the old feature request, as we generally prefer not to reopen old feature requests the initial implemntation of which was successfully completed.
+
+
 New issues should include all relevant information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

introduction/support.rst

@@ -77,7 +77,7 @@ It’s always possible that a bad actor could try to impersonate any member of t
 
 Given that there may be impostors and others trying to lead you astray, how should you sort the good advice from the bad? This is up to each individual to decide, but it helps to know that many members of our community have proven themselves knowledgeable through their :doc:`contributions </introduction/contributing>` to the project. Often, these individuals sign their messages with the same key as (or another key authenticated by) the one they use to :doc:`sign their contributions </developer/code/code-signing>`.
 
-For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or `contributing to the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
+For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or :doc:`contributing to the documentation </developer/general/how-to-edit-the-documentation>`. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
 
 Discussion guidelines
 ---------------------
@@ -121,7 +121,7 @@ Report issues and submit changes in the right places
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, `submit the change <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__.
+The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :doc:`submit the change </developer/general/how-to-edit-the-documentation>`.
 
 Moderation
 ^^^^^^^^^^