2024-05-21 14:59:46 -04:00
|
|
|
|
=============================
|
|
|
|
|
|
How to edit the documentation
|
|
|
|
|
|
=============================
|
|
|
|
|
|
|
|
|
|
|
|
|
2023-12-28 05:44:25 -05:00
|
|
|
|
*Also see the* :doc:`documentation style guide </developer/general/documentation-style-guide>`.
|
2024-05-21 14:59:46 -04:00
|
|
|
|
|
|
|
|
|
|
Qubes OS documentation pages are stored as plain text Markdown files in
|
|
|
|
|
|
the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository. By
|
|
|
|
|
|
cloning and regularly pulling from this repo, users can maintain their
|
|
|
|
|
|
own up-to-date offline copy of all Qubes documentation rather than
|
|
|
|
|
|
relying solely on the web.
|
|
|
|
|
|
|
|
|
|
|
|
The documentation is a volunteer community effort. People like you are
|
|
|
|
|
|
constantly working to make it better. If you notice something that can
|
|
|
|
|
|
be fixed or improved, please follow the steps below to open a pull
|
|
|
|
|
|
request!
|
|
|
|
|
|
|
|
|
|
|
|
How to submit a pull request
|
|
|
|
|
|
----------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
We keep all the documentation in
|
|
|
|
|
|
`qubes-doc <https://github.com/QubesOS/qubes-doc>`__, a dedicated Git
|
|
|
|
|
|
repository hosted on `GitHub <https://github.com/>`__. Thanks to
|
|
|
|
|
|
GitHub’s easy web interface, you can edit the documentation even if
|
|
|
|
|
|
you’re not familiar with Git or the command line! All you need is a free
|
|
|
|
|
|
GitHub account.
|
|
|
|
|
|
|
|
|
|
|
|
A few notes before we get started:
|
|
|
|
|
|
|
|
|
|
|
|
- Since Qubes is a security-oriented project, every documentation
|
|
|
|
|
|
change will be `reviewed <#security>`__ before it’s accepted. This
|
|
|
|
|
|
allows us to maintain quality control and protect our users.
|
|
|
|
|
|
|
|
|
|
|
|
- To give your contribution a better chance of being accepted, please
|
|
|
|
|
|
follow our :doc:`documentation style guide </developer/general/documentation-style-guide>`.
|
|
|
|
|
|
|
|
|
|
|
|
- We don’t want you to spend time and effort on a contribution that we
|
|
|
|
|
|
can’t accept. If your contribution would take a lot of time, please
|
|
|
|
|
|
:doc:`file an issue </introduction/issue-tracking>` for it first so that we can
|
|
|
|
|
|
make sure we’re on the same page before significant works begins.
|
|
|
|
|
|
|
|
|
|
|
|
- Alternatively, you may already have written content that doesn’t
|
|
|
|
|
|
conform to these guidelines, but you’d be willing to modify it so
|
|
|
|
|
|
that it does. In this case, you can still submit it by following the
|
|
|
|
|
|
instructions below. Just make a note in your pull request (PR) that
|
|
|
|
|
|
you’re aware of the changes that need to be made and that you’re just
|
|
|
|
|
|
asking for the content to be reviewed before you spend time making
|
|
|
|
|
|
those changes.
|
|
|
|
|
|
|
|
|
|
|
|
- Finally, if you’ve written something that doesn’t belong in qubes-doc
|
|
|
|
|
|
but that would be beneficial to the Qubes community, please consider
|
|
|
|
|
|
adding it to the :ref:`external documentation <developer/general/documentation-style-guide:core vs. external documentation>`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(**Advanced users:** If you’re already familiar with GitHub or wish to
|
|
|
|
|
|
work from the command line, you can skip the rest of this section. All
|
|
|
|
|
|
you need to do to contribute is to `fork and clone <https://guides.github.com/activities/forking/>`__ the
|
|
|
|
|
|
`qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repo, make your
|
|
|
|
|
|
changes, then `submit a pull request <https://help.github.com/articles/using-pull-requests/>`__.)
|
|
|
|
|
|
|
|
|
|
|
|
Ok, let’s begin. Every documentation page has a “Page Source on GitHub”
|
|
|
|
|
|
button. Depending on the size of your screen, it may either be on the
|
|
|
|
|
|
side (larger screens) or on the bottom (smaller screens).
|
|
|
|
|
|
|
|
|
|
|
|
|page-source-button|
|
|
|
|
|
|
|
|
|
|
|
|
When you click on it, you’ll be taken to the source file — usually a
|
|
|
|
|
|
Markdown (``.md``) file — on GitHub. On this page, there will be a
|
|
|
|
|
|
button to edit the file.
|
|
|
|
|
|
|
|
|
|
|
|
|github-edit|
|
|
|
|
|
|
|
|
|
|
|
|
You’ll be prompted to sign in with your GitHub username and password (if
|
|
|
|
|
|
you aren’t already logged in). 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). It’s easy — just click the
|
|
|
|
|
|
big green button on the next page. This step is only needed the first
|
|
|
|
|
|
time you make a contribution.
|
|
|
|
|
|
|
|
|
|
|
|
|fork|
|
|
|
|
|
|
|
|
|
|
|
|
Now you can make your modifications. You can also preview the changes to
|
|
|
|
|
|
see how they’ll be formatted by clicking the “Preview changes” tab. If
|
|
|
|
|
|
you want to add images, please see `How to add images <#how-to-add-images>`__. If you’re making formatting changes,
|
|
|
|
|
|
please `render the site locally <https://github.com/QubesOS/qubesos.github.io#instructions>`__
|
|
|
|
|
|
to verify that everything looks correct before submitting any changes.
|
|
|
|
|
|
|
|
|
|
|
|
|edit|
|
|
|
|
|
|
|
|
|
|
|
|
Once you’re finished, describe your changes at the bottom and click
|
|
|
|
|
|
“Propose file change”.
|
|
|
|
|
|
|
|
|
|
|
|
|commit|
|
|
|
|
|
|
|
|
|
|
|
|
After that, you’ll see exactly what modifications you’ve made. At this
|
|
|
|
|
|
stage, those changes are still in your own copy of the documentation
|
|
|
|
|
|
(“fork”). If everything looks good, send those changes to us by pressing
|
|
|
|
|
|
the “Create pull request” button.
|
|
|
|
|
|
|
|
|
|
|
|
|pull-request|
|
|
|
|
|
|
|
|
|
|
|
|
You will be able to adjust the pull request message and title there. In
|
|
|
|
|
|
most cases, the defaults are ok, so you can just confirm by pressing the
|
|
|
|
|
|
“Create pull request” button again. However, if you’re not ready for
|
|
|
|
|
|
your PR to be reviewed or merged yet, please `make a draft PR instead <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`__.
|
|
|
|
|
|
|
|
|
|
|
|
|pull-request-confirm|
|
|
|
|
|
|
|
|
|
|
|
|
If any of your changes should be reflected in the :doc:`documentation index (a.k.a. table of contents) </index>` — for example, if you’re adding a
|
|
|
|
|
|
new page, changing the title of an existing page, or removing a page —
|
|
|
|
|
|
please see `How to edit the documentation index <#how-to-edit-the-documentation-index>`__.
|
|
|
|
|
|
|
|
|
|
|
|
That’s all! We will review your changes. If everything looks good, we’ll
|
|
|
|
|
|
pull them into the official documentation. Otherwise, we may have some
|
|
|
|
|
|
questions for you, which we’ll post in a comment on your pull request.
|
|
|
|
|
|
(GitHub will automatically notify you if we do.) If, for some reason, we
|
|
|
|
|
|
can’t accept your pull request, we’ll post a comment explaining why we
|
|
|
|
|
|
can’t.
|
|
|
|
|
|
|
|
|
|
|
|
|done|
|
|
|
|
|
|
|
|
|
|
|
|
How to edit the documentation index
|
|
|
|
|
|
-----------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The source file for the :doc:`documentation index (a.k.a. table of contents) </index>` is
|
|
|
|
|
|
`doc-index.yml <https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml>`__.
|
|
|
|
|
|
|
|
|
|
|
|
Editing this file will change what appears on the documentation index.
|
|
|
|
|
|
If your pull request (PR) adds, removes, or edits anything that should
|
|
|
|
|
|
be reflected in the documentation index, please make sure you also
|
|
|
|
|
|
submit an associated pull request against this file.
|
|
|
|
|
|
|
|
|
|
|
|
How to add images
|
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To add an image to a page, use the following syntax in the main document
|
|
|
|
|
|
(see :ref:`here <developer/general/documentation-style-guide:image linking>` for why
|
|
|
|
|
|
this syntax is important).
|
|
|
|
|
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
|
|
|
|
|
|
|
[](/attachment/doc/image.png)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Then, submit your image(s) in a separate pull request to the
|
|
|
|
|
|
`qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__
|
|
|
|
|
|
repository using the same path and filename. This is the only permitted
|
|
|
|
|
|
way to include images. Do not link to images on other websites.
|
|
|
|
|
|
|
|
|
|
|
|
Serving the website locally
|
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can serve the website offline on your local machine by following
|
|
|
|
|
|
`these instructions <https://github.com/QubesOS/qubesos.github.io#instructions>`__.
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
Security
|
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*Also see:* :ref:`Should I trust this website? <introduction/faq:should i trust this website?>`
|
|
|
|
|
|
|
|
|
|
|
|
All pull requests (PRs) against
|
|
|
|
|
|
`qubes-doc <https://github.com/QubesOS/qubes-doc>`__ must pass review
|
|
|
|
|
|
prior to be merged, except in the case of :ref:`external documentation <index:external documentation>` (see
|
|
|
|
|
|
`#4693 <https://github.com/QubesOS/qubes-issues/issues/4693>`__). This
|
|
|
|
|
|
process is designed to ensure that contributed text is accurate and
|
|
|
|
|
|
non-malicious. This process is a best effort that should provide a
|
|
|
|
|
|
reasonable degree of assurance, but it is not foolproof. For example,
|
|
|
|
|
|
all text characters are checked for ANSI escape sequences. However,
|
|
|
|
|
|
binaries, such as images, are simply checked to ensure they appear or
|
|
|
|
|
|
function the way they should when the website is rendered. They are not
|
|
|
|
|
|
further analyzed in an attempt to determine whether they are malicious.
|
|
|
|
|
|
|
|
|
|
|
|
Once a pull request passes review, the reviewer should add a signed
|
2023-12-28 05:44:25 -05:00
|
|
|
|
comment stating, “Passed review as of ``<LATEST_COMMIT>`` ” (or similar).
|
2024-05-21 14:59:46 -04:00
|
|
|
|
The documentation maintainer then verifies that the pull request is
|
|
|
|
|
|
mechanically sound (no merge conflicts, broken links, ANSI escapes,
|
|
|
|
|
|
etc.). If so, the documentation maintainer then merges the pull request,
|
|
|
|
|
|
adds a PGP-signed tag to the latest commit (usually the merge commit),
|
|
|
|
|
|
then pushes to the remote. In cases in which another reviewer is not
|
|
|
|
|
|
required, the documentation maintainer may review the pull request (in
|
|
|
|
|
|
which case no signed comment is necessary, since it would be redundant
|
|
|
|
|
|
with the signed tag).
|
|
|
|
|
|
|
|
|
|
|
|
Questions, problems, and improvements
|
|
|
|
|
|
-------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you have a question about something you read in the documentation or
|
|
|
|
|
|
about how to edit the documentation, please post it on the
|
|
|
|
|
|
`forum <https://forum.qubes-os.org/>`__ or send it to the appropriate
|
|
|
|
|
|
:doc:`mailing list </introduction/support>`. If you see that something in the
|
|
|
|
|
|
documentation should be fixed or improved, please
|
|
|
|
|
|
`contribute <#how-to-submit-a-pull-request>`__ the change yourself. To
|
|
|
|
|
|
report an issue with the documentation, please follow our standard
|
|
|
|
|
|
:doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an
|
|
|
|
|
|
issue with the documentation, you will likely be asked to submit a pull
|
|
|
|
|
|
request for it, unless there is a clear indication in your report that
|
|
|
|
|
|
you are not willing or able to do so.)
|
|
|
|
|
|
|
|
|
|
|
|
.. |page-source-button| image:: /attachment/doc/doc-pr_01_page-source-button.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |fork| image:: /attachment/doc/doc-pr_04_fork.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |edit| image:: /attachment/doc/doc-pr_05_edit.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |commit| image:: /attachment/doc/doc-pr_06_commit-msg.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |pull-request| image:: /attachment/doc/doc-pr_07_review-changes.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |pull-request-confirm| image:: /attachment/doc/doc-pr_08_create-pull-request.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. |done| image:: /attachment/doc/doc-pr_09_done.png
|
|
|
|
|
|
|
