From 0e5a97785c2d57b4bdf83229622c9342594b051d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 27 Oct 2020 19:23:57 -0700 Subject: [PATCH] Add information about doc review security --- developer/general/doc-guidelines.md | 19 ++++++++++++++++++- introduction/faq.md | 2 +- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index 79bb1d26..55f8d9a8 100644 --- a/developer/general/doc-guidelines.md +++ b/developer/general/doc-guidelines.md @@ -18,6 +18,22 @@ The documentation is a community effort. Volunteers work hard trying to keep eve If you notice a problem or some way it can be improved, please [edit the documentation][contribute]! +Security +-------- + +All pull requests against [qubes-doc] must pass review prior to be merged, except in the case of [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 ------------------------------------- @@ -304,4 +320,5 @@ Please try to write good commit messages, according to the [git-commit]: /doc/coding-style/#commit-message-guidelines [render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions [qubes-attachment]: https://github.com/QubesOS/qubes-attachment - +[external documentation]: /doc/#external-documentation +[#4693]: https://github.com/QubesOS/qubes-issues/issues/4693 diff --git a/introduction/faq.md b/introduction/faq.md index 5839257f..3ea75e7f 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -278,7 +278,7 @@ This website is hosted on [GitHub Pages][] ([why?][]). Therefore, it is largely outside of our control. We don't consider this a problem, however, since we explicitly [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], [verify the PGP signatures on the commits and/or tags] signed by the [doc-signing keys], then either [render the site on your local machine][render] 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][Markdown]. +Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo], [verify the PGP signatures on the commits and/or tags] signed by the [doc-signing keys] (which indicates that the content has undergone review per our [documentation guidelines]), then either [render the site on your local machine][render] 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][Markdown]. 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"?