Merge pull request #8 from freedomofpress/release-mgmt

Update release management guidelines

Author: zenmonkeykstop

README.md

@@ -4,7 +4,7 @@
 
 SecureDrop is an open-source whistleblower submission system that media organizations can use to securely accept documents from, and communicate with anonymous sources. It was originally created by the late Aaron Swartz and is currently managed by the [Freedom of the Press Foundation](https://freedom.press).
 
-This is repository is still in beta. It will eventually be used to build the [public documentation](https://docs.securedrop.org/en/stable/) for SecureDrop.
+This repository is used to build the [public documentation](https://docs.securedrop.org/en/stable/) for SecureDrop.
 
 ## Quickstart
 

docs/development/documentation_guidelines.rst

@@ -25,7 +25,7 @@ To get started editing the docs:
 
       pip install --no-deps --require-hashes -r securedrop/requirements/python3/develop-requirements.txt
 
-.. include:: ../includes/virtualenv.txt   
+.. include:: ../includes/virtualenv.txt
 
 3. Build the docs for viewing in your web browser:
 
@@ -75,13 +75,13 @@ To update these screenshots automatically you can run:
 
 .. code:: sh
 
-   make update-user-guides
+   DOCS_REPO_DIR=/path/to/docs make update-user-guides
 
 This will generate screenshots for each page in the web application and copy
-them to the folder under ``docs/images/manual/screenshots`` where they will
-replace the existing screenshots. Stage for commit any screenshots you wish to
-update. If you wish to update all screenshots, simply stage for commit all
-changed files in that directory.
+them to the folder ``docs/images/manual/screenshots`` in your documentation
+repository checkout, where they will replace the existing screenshots. Stage for
+commit any screenshots you wish to update. If you wish to update all screenshots,
+simply stage for commit all changed files in that directory.
 
 Integration with Read the Docs
 ------------------------------
@@ -190,4 +190,4 @@ Capitalize all section headings in title case:
      ================
 
      Read the docs
-     -------------
+     -------------

docs/development/i18n.rst

@@ -207,7 +207,7 @@ repo root:
 
     $ git checkout -b i18n-merge origin/develop
     $ securedrop/bin/dev-shell ./i18n_tool.py --verbose update-from-weblate
-    $ securedrop/bin/dev-shell ./i18n_tool.py --verbose update-docs
+    $ securedrop/bin/dev-shell ./i18n_tool.py --verbose update-docs --docs-repo-dir /path/to/documentation
 
 You now have the latest translations on your ``i18n-merge`` branch.
 

docs/development/release_management.rst

@@ -176,8 +176,14 @@ Pre-Release
      is done, ensure that no changes involving string changes are
      backported into the release branch.
 
-   * Ensure that a draft of the release notes are prepared and shared
-     with the community for feedback.
+   * Work with the Communications Manager to ensure that a draft of the release
+     notes are prepared and shared for review, and that a draft PR is prepared
+     into the ``securedrop-docs`` repository which:
+
+     - bumps the SecureDrop version of the documentation using the ``update_version.sh``
+       script in that repository;
+     - adds upgrade instructions and other release-specific technical documentation;
+     - updates the screenshots, if warranted;
 
 Release Process
 ---------------
@@ -262,16 +268,32 @@ Release Process
    ``apt.freedom.press``.
 #. The reviewer must delete the ``release`` branch so that it can be re-created
    during the next release.
-#. Update the `public documentation <https://docs.securedrop.org/en/stable>`_ by
-   synchronising the ``stable`` branch with the release branch:
+#. Update the `public documentation <https://docs.securedrop.org/>`_:
+
+  * Review and merge the ``securedrop-docs`` PR that bumps the version and adds
+    the upgrade documentation for this release.
+
+  * Verify that there are no changes on the ``main`` branch of ``securedrop-docs``
+    that should not be released into the stable version of the documentation.
+
+    If necessary, you can create a branch from an earlier commit. Follow the
+    ``release/<major>.<minor>.<patch>`` convention for the branch name in
+    ``securedrop-docs``, and cherry-pick at least the changes from the PR above
+    onto it via a backport PR.
+
+  * Create a tag signed with your developer key in the format
+    ``<major>.<minor>.<patch>`` on the ``HEAD`` of the ``main`` branch or of the
+    docs release branch you created in the previous step. ::
+
+      git tag -as <major>.<minor>.<patch>
+      git push origin <major>.<minor>.<patch>
 
-   * If a repository maintainer is available, remove the branch protection on
-     the ``stable`` branch, hard-reset it to the release branch, and force push
-     ``stable``. Then restore branch protection on ``stable``.
+    This will update the stable version of the documentation.
 
-   * If a maintainer is not available, create a PR with the release branch
-     changes using ``stable`` as the base. Version number updates will cause
-     conflicts which must be resolved manually before issuing the PR.
+  * Subsequent changes to the stable version should be tagged with PEP-440
+    conformant `post-release separators <https://www.python.org/dev/peps/pep-0440/#post-release-separators>`__
+    in the format ``<major>.<minor>.<patch>-1``,  ``<major>.<minor>.<patch>-2``,
+    and so on.
 
 #. Verify that the public documentation has been updated, by checking the
    `ReadTheDocs build history <https://readthedocs.org/projects/securedrop/builds/>`_.