Add upgrade guide for 2.6.0 (#468)

* Add upgrade guide for 2.6.0

* Remove outdated upgrade guides and include pyproject.toml in update_version script.

* Add a reference to the Tail 5.14 security advisory in the 2.6.0 upgrade guide.

* Update docs/upgrade/2.5.2_to_2.6.0.rst

Co-authored-by: Kunal Mehta <[email protected]>

---------

Co-authored-by: Nathan Dyer <[email protected]>
Co-authored-by: Kunal Mehta <[email protected]>

docs/admin/installation/set_up_admin_tails.rst

@@ -139,7 +139,7 @@ signed with the release signing key:
 
     cd ~/Persistent/securedrop/
     git fetch --tags
-    git tag -v 2.5.2
+    git tag -v 2.6.0
 
 The output should include the following two lines:
 
@@ -160,9 +160,9 @@ screen of your workstation. If it does, you can check out the new release:
 
 .. code:: sh
 
-    git checkout 2.5.2
+    git checkout 2.6.0
 
-.. important:: If you see the warning ``refname '2.5.2' is ambiguous`` in the
+.. important:: If you see the warning ``refname '2.6.0' is ambiguous`` in the
                output, we recommend that you contact us immediately at
                [email protected] (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).
 

docs/admin/maintenance/backup_and_restore.rst

@@ -229,7 +229,7 @@ Migrating Using a V2+V3 or V3-Only Backup
 
       cd ~/Persistent/securedrop/
       git fetch --tags
-      git tag -v 2.5.2
+      git tag -v 2.6.0
 
    The output should include the following two lines:
 
@@ -250,10 +250,10 @@ Migrating Using a V2+V3 or V3-Only Backup
 
    .. code:: sh
 
-      git checkout 2.5.2
+      git checkout 2.6.0
 
    .. important::
-      If you see the warning ``refname '2.5.2' is ambiguous`` in the
+      If you see the warning ``refname '2.6.0' is ambiguous`` in the
       output, we recommend that you contact us immediately at
       [email protected]
       (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).
@@ -472,7 +472,7 @@ source accounts, and journalist accounts. To do so, follow the steps below:
 
       cd ~/Persistent/securedrop/
       git fetch --tags
-      git tag -v 2.5.2
+      git tag -v 2.6.0
 
    The output should include the following two lines:
 
@@ -491,11 +491,11 @@ source accounts, and journalist accounts. To do so, follow the steps below:
 
    .. code:: sh
 
-      git checkout 2.5.2
+      git checkout 2.6.0
 
 
    .. important::
-      If you see the warning ``refname '2.5.2' is ambiguous`` in the
+      If you see the warning ``refname '2.6.0' is ambiguous`` in the
       output, we recommend that you contact us immediately at
       [email protected] (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).
 

docs/conf.py

@@ -46,7 +46,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.5.2"
+version = "2.6.0"
 # The full version, including alpha/beta/rc tags.
 # On the live site, this will be overridden to "stable" or "latest".
 release = os.environ.get("SECUREDROP_DOCS_RELEASE", version)

docs/index.rst

@@ -146,13 +146,12 @@ Get Started
    :maxdepth: 2
    :hidden:
 
+   upgrade/2.5.2_to_2.6.0.rst
    upgrade/2.5.1_to_2.5.2.rst
    upgrade/2.5.0_to_2.5.1.rst
    upgrade/2.4.2_to_2.5.0.rst
    upgrade/2.4.1_to_2.4.2.rst
    upgrade/2.4.0_to_2.4.1.rst
-   upgrade/2.3.2_to_2.4.0.rst
-   upgrade/2.3.1_to_2.3.2.rst
 
 Get Involved
 ^^^^^^^^^^^^

docs/upgrade/2.5.1_to_2.5.2.rst

@@ -1,5 +1,3 @@
-.. _latest_upgrade_guide:
-
 Upgrade from 2.5.1 to 2.5.2
 ===========================
 

docs/upgrade/2.3.2_to_2.4.0.rst → docs/upgrade/2.5.2_to_2.6.0.rst

@@ -1,28 +1,46 @@
-Upgrade from 2.3.2 to 2.4.0
+.. _latest_upgrade_guide:
+
+Upgrade from 2.5.2 to 2.6.0
 ===========================
 
-Update Servers to SecureDrop 2.4.0
+Update Servers to SecureDrop 2.6.0
 ----------------------------------
 Servers running Ubuntu 20.04 will be updated to the latest version of SecureDrop
 automatically within 24 hours of the release.
 
-Update Workstations to SecureDrop 2.4.0
+Update Workstations to SecureDrop 2.6.0
 ---------------------------------------
 
+Updating Tails and replacing short passphrases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Before upgrading your Workstations to SecureDrop 2.6.0, we 
+strongly recommend that you first upgrade to Tails 5.14, which includes
+important updates to disk encryption and passphrase hashing algorithms. 
+
+We also recommend updating all other encrypted drives to LUKS2, and ensuring
+you have strong passphrases.
+
+We have issued a Security Advisory, which provides detailed instructions for
+updating the Workstations, as well as any other encrypted drives. You can find
+that `advisory on the SecureDrop website.
+<https://securedrop.org/news/security-advisory-update-encrypted-usb-drives-and-replace-short-passphrases/>`_
+
+
+Using the graphical updater
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. note::
 
    If you encounter errors with the graphical updater, perform a
    manual update. This will ensure that you have imported the new
    `SecureDrop release signing key <https://media.securedrop.org/media/documents/signing-key-transition.txt>`_.
 
-Using the graphical updater
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 On the next boot of your SecureDrop *Journalist* and *Admin Workstations*,
 the *SecureDrop Workstation Updater* will alert you to workstation updates. You
 must have `configured an administrator password <https://tails.boum.org/doc/first_steps/welcome_screen/administration_password/>`_
 on the Tails welcome screen in order to use the graphical updater.
 
-Perform the update to 2.4.0 by clicking "Update Now":
+Perform the update to 2.6.0 by clicking "Update Now":
 
 .. image:: ../images/securedrop-updater.png
 
@@ -42,7 +60,7 @@ update by running the following commands: ::
   git fetch --tags
   gpg --keyserver hkps://keys.openpgp.org --recv-key \
    "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3"
-  git tag -v 2.4.0
+  git tag -v 2.6.0
 
 The output should include the following two lines: ::
 
@@ -55,9 +73,9 @@ on the screen of your workstation. A warning that the key is not certified
 is normal and expected. If the output includes the lines above, you can check
 out the new release: ::
 
-    git checkout 2.4.0
+    git checkout 2.6.0
 
-.. important:: If you do see the warning "refname '2.4.0' is ambiguous" in the
+.. important:: If you do see the warning "refname '2.6.0' is ambiguous" in the
   output, we recommend that you contact us immediately at [email protected]
   (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).
 
@@ -66,29 +84,23 @@ Finally, run the following commands: ::
   ./securedrop-admin setup
   ./securedrop-admin tailsconfig
 
-Tor Browser security issue
---------------------------
-
-Tails has `published an advisory <https://tails.boum.org/security/prototype_pollution/>`__
-for a serious security issue in Tor Browser affecting all versions of Tails. Administrators
-and journalists should disable JavaScript by `setting Tor Browser’s security level to “Safest”
-<https://tails.boum.org/doc/anonymous_internet/Tor_Browser/index.en.html#security-level>`__
-until a fix is available (expected on May 31, 2022). If you are using Tor Browser in Tails
-for non-SecureDrop browsing, we recommend restarting Tor Browser before and after using it
-for SecureDrop.
-
-Upgrade from Tails 4 to Tails 5
--------------------------------
+Update Tails
+------------
+Follow the graphical prompts to update to the latest version of the Tails
+operating system on your *Admin* and *Journalist Workstations*.
 
 If you have not already done so, you must manually upgrade from the Tails 4 release
 series to the Tails 5 series.
 
+Upgrade from Tails 4 to Tails 5
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. important::
 
    You must upgrade your workstations to the latest version of SecureDrop by following
    the steps above *before* upgrading to the Tails 5 series. You can verify the version
    of SecureDrop by running ``git status`` in your ``~/Persistent/securedrop`` directory.
-   The output should include "HEAD detached at 2.4.0".
+   The output should include "HEAD detached at 2.6.0".
 
 The Tails 5 series is based on Debian 11 ("Bullseye"). Among the most noticeable
 changes is the switch to a new frontend for GnuPG called Kleopatra. Once you
@@ -124,24 +136,9 @@ steps to complete the upgrade:
 When prompted by Tails to "Install Only Once" or "Install Every Time", click
 **Install Every Time** (this is a change from previous versions of Tails).
 
-Language support changes
-------------------------
-
-We are pleased to announce support for Portuguese (Portugal). To enable this language,
-on the *Admin Workstation* run: ::
-
-  ./securedrop-admin sdconfig
-
-When prompted, add ``pt_PT`` to the list of locales. Then run: ::
-
-  ./securedrop-admin install
-
-We are currently lacking translators for Hindi and Romanian, which are both at risk
-of being removed in the next SecureDrop release. If you speak either language or know
-someone who does, please see our instructions on `contributing translations <https://developers.securedrop.org/en/latest/translations.html>`_.
-
 .. include:: ../includes/backup-and-update-reminders.txt
 
+
 Getting Support
 ---------------
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "securedrop-docs"
-version = "2.5.2"
+version = "2.6.0"
 description = "SecureDrop documentation for journalists, sources and administrators"
 authors = ["SecureDrop team <[email protected]>"]
 readme = "README.md"

update_version.sh

@@ -11,9 +11,10 @@ if [ -z "$NEW_VERSION" ]; then
 fi
 readonly OLD_VERSION=$(grep -oP '(?<=^version \= ")\d+\.\d+\.\d+' docs/conf.py)
 
-sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/set_up_admin_tails.rst
-sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/backup_and_restore.rst
+sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/admin/installation/set_up_admin_tails.rst
+sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/admin/maintenance/backup_and_restore.rst
 sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/conf.py
+sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" pyproject.toml
 
 echo "Versions updated. Verify the results with 'git diff' and be sure to tag"
 echo "a new stable version as part of the release process."