doc: Update the release checklist

1 files changed, 185 insertions, 62 deletions

diff --git a/doc/release-checklist.md b/doc/release-checklist.md
index 26cb6735..a3ceac34 100644
--- a/doc/release-checklist.md
+++ b/doc/release-checklist.md
@@ -1,63 +1,186 @@
-This is a checklist for doing Sequoia releases:
-
-  1. Decide which component to release, we'll call it `FOO`.
-  1. Decide on the new version number `XXX`.
-  1. Starting from `origin/main`, create a branch `staging` for the release.
-  1. Bump `version = "XXX"` in `FOO/Cargo.toml`
-  1. For all 'Cargo.toml's: Bump intra-workspace dependencies if
-     necessary.
-       - For instance, if releasing `sequoia-openpgp` and `sq` depends
-         on features that are being released, then bump the dependency
-         in `sq/Cargo.toml`.
-  1. Run `cargo check -p FOO --features sequoia-openpgp/crypto-nettle`
-     (this implicitly updates `Cargo.lock`)
-  1. Update dependencies and run tests.
-       - Use the exact Rust toolchain version of the current Sequoia
-         MSRV (refer to `README.md`):  `rustup default 1.xx`
-       - Run `cargo update -p FOO` to update the dependencies.  If
-         some dependency is updated and breaks due to our MSRV, find a
-         good version of that dependency and select it using
-         e.g. `cargo update -p backtrace --precise 3.46`.
-       - Run `make -f .Makefile check`.
-  1. Commit changes to `Cargo.toml` and `Cargo.lock`.
-  1. If releasing `sequoia-openpgp`, update
-     https://sequoia-pgp.org/tmp/stats.txt by running:
-      - `cargo run -p sequoia-openpgp --example statistics --release -- .../sks-dump-*.pgp --features sequoia-openpgp/crypto-nettle > /tmp/stats.txt`
-      - `scp /tmp/stats.txt sequoia@sequoia-pgp.org:sequoia-pgp.org/tmp`
-  1. If releasing sq, update the manpage:
-      - Clone https://gitlab.com/sequoia-pgp/manpage-maker to a
-        separate location.
-      - Add symlinks and run as described in the manpage-maker's readme
-      - Copy man-sq*/*.1 to sequoia/sq/man-sq*
-      - Make a commit with the message "sq, sqv: Update manpage."
-  1. Make a commit with the message `FOO: Release XXX.`.
-       - Push this to gitlab as `staging`, create a merge
+This is a checklist for doing releases.
+
+1. Create a new milestone for the planned release.
+
+1. Announce your intention to do a release on irc, and ask if anyone
+   has any changes that want merged before the release, or issues that
+   should be fixed.  Ask them to add them to the milestone.
+
+1. Go to the project's repository and scan the open issues and MRs.
+   If there is something relevant for the release, add it to the
+   milestone.
+
+1. Work through the milestone backlog.
+
+1. Preparation for the actual release.
+
+    We set some variables here that the code snippets below use.
+
+    Select the features to use.  Leave it empty to use the default:
+    ```shell
+    FEATURES=""
+    ```
+
+    In projects where you need to select a specific backend, try:
+    ```shell
+    FEATURES="--no-default-features --features crypto-openssl"
+    ```
+
+    When building a project in a workspace, like `sequoia-openpgp`, do something like:
+    ```shell
+    FEATURES="-p sequoia-openpgp"
+    ```
+
+    Optionally set `CARGO_TARGET_DIR`
+    ```shell
+    export CARGO_TARGET_DIR=$(mktemp -d)
+    ```
+
+1. Make sure your repository is up to date:
+    ```
+    git fetch
+    ```
+
+1. Start from `origin/main`, and create a branch `staging`:
+    ```
+    git checkout -b staging origin/main
+    ```
+
+1. Update Cargo.lock, and run checks locally:
+
+    - Use the project's exact MSRV version.  This is important when
+      updating dependencies, and for `cargo publish`.
+    ```
+    MSRV=$(sed -nE 's/rust-version\s+=\s+"([^"]+)"/\1/p' < Cargo.toml)
+    rustup default "$MSRV"
+    ```
+
+    - Update the dependencies and run the tests:
+
+    ```
+    cargo update
+    cargo build --release $FEATURES && \
+    cargo test --release $FEATURES && \
+    cargo doc --no-deps --release $FEATURES
+
+    git add Cargo.lock
+    if [ git diff --cached --exit-code ]; then
+      git commit -m "Update dependencies."
+    fi
+    ```
+
+    - If some dependency is updated and breaks due to our MSRV, find a
+    good version of that dependency and select it using e.g. `cargo
+    update -p backtrace --precise 3.46`.
+
+    - Audit any new indirect dependencies.
+
+    - Check in any updates with the commit message: "Update
+      Cargo.lock".
+
+1. Check for out-of-date dependencies and see if they can be upgraded:
+
+    ```
+    cargo outdated -d 1
+    editor Cargo.toml # Update version
+    cargo update -p PACKAGE --precise VERSION
+    cargo build --release $FEATURES && cargo test --release $FEATURES && cargo doc --no-deps --release $FEATURES
+    ```
+
+   Add a commit for each dependency or group of dependencies that is
+   upgraded ("Upgrade PACKAGE").  Sometimes it is possible to upgrade
+   a dependency, but not to the latest version.  Sometimes there is a
+   semver change, but we don't rely on the change.  In that case, try
+   using a version range:
+
+    ```toml
+    memsec = { version = ">=0.5, <0.7", default-features = false }
+    ```
+
+   Note: if specifying a lower bound, always specify an upper bound
+   otherwise things may break in the future.
+
+1. Bump the version in Cargo.toml to `XXX`.
+    ```
+    cargo set-version "$VERSION"
+    ```
+
+1. Bump the version in `README.md` to `XXX`, if necessary.
+
+1. Make a commit with the message `Release XXX.` or `project: Release XXX.`.
+    ```
+    git commit -a -S -m "Release $VERSION."
+    ```
+
+1. Push this to gitlab as `staging`, create a merge
          request, wait for CI.
-  1. Make sure `cargo publish` works:
-       - `mkdir /tmp/sequoia-staging`
-       - `cd /tmp/sequoia-staging`
-       - `git clone git@gitlab.com:sequoia-pgp/sequoia.git`
-       - `cd sequoia`
-       - `git checkout origin/staging`
-       - `cargo publish -p FOO --dry-run --features sequoia-openpgp/crypto-nettle`
-  1. Wait until CI and `cargo publish -p FOO --dry-run` are successful.  In
-     case of errors, correct them, and go back to the step creating
-     the release commit.
-  1. Run `cargo publish -p FOO --features
-     sequoia-openpgp/crypto-nettle`, wait til it succeeds
-  1. Merge the merge request
-  1. Make a tag `FOO/vXXX` with the message `FOO: Release XXX.` signed
-     with an offline key, which has been certified by our
-     `openpgp-ca@sequoia-pgp.org` key.
-  1. Push the signed tag `FOO/vXXX`.
-  1. Regenerate `docs.sequoia-pgp.org`.
-       - `cd /tmp/sequoia-staging`
-       - `git clone git@gitlab.com:sequoia-pgp/docs.sequoia-pgp.org.git`
-       - `cd docs.sequoia-pgp.org`
-       - `make deploy`
-  1. Announce the release.
-       - IRC
-       - mailing list (`announce@lists.sequoia-pgp.org`,
-         `devel@lists.sequoia-pgp.org`, optionally cc `lwn@lwn.net` if
-         there are particularly interesting changes)
-       - web site
+    ```
+    git push origin staging
+    ```
+
+1. Make sure `cargo publish` works:
+
+    ```
+    ORIGIN=$(git remote get-url origin)
+    cd $(mktemp -d)
+    git clone $ORIGIN source
+    cd source
+    git checkout origin/staging
+    cargo publish --dry-run $FEATURES
+    ```
+
+    Note: when working with workspaces and cargo <1.68, [the top-level
+    `Cargo.lock` file will be
+    ignored](https://github.com/rust-lang/cargo/pull/11477).  This can
+    be worked around by using a newer rustc or doing something like:
+
+    ```shell
+    cp Cargo.lock openpgp
+    cargo publish -p sequoia-openpgp --locked --allow-dirty
+    ```
+
+1. Wait until CI and `cargo publish --dry-run` are successful.  In
+   case of errors, correct them, and go back to the step creating
+   the release commit.
+
+    ```
+    if [[ "$ORIGIN" =~ ^git@([^:]+):([^/]+)/([^.]+).git$ ]]; then
+      while [ $( curl -sSL "https://${BASH_REMATCH[1]}/api/v4/projects/${BASH_REMATCH[2]}%2F${BASH_REMATCH[3]}/pipelines?ref=staging&sha=$(git rev-parse HEAD)" | jq 'map(select(.status != "success")) | length == 0' ) != "true" ]; do
+        echo "Pipelines still running... (or failed)"
+        sleep 9
+      done
+    else
+      echo Origin not supported
+      exit 1
+    fi
+    ```
+
+1. Run `cargo publish`
+
+    ```
+    cargo publish
+    ```
+
+1. Merge the merge request
+
+1. Make a tag `vXXX` with the message `Release XXX.` or `project:
+   Release XXX.`, as appropriate.  Sign it with an offline key that
+   has been certified by our `openpgp-ca@sequoia-pgp.org` key:
+
+    ```
+    git tag -s -m "Release $VERSION." v$VERSION
+    git verify-tag v$VERSION
+    ```
+
+1. Push the signed tag `vXXX`:
+
+    ```
+    git push origin v$VERSION
+    ```
+
+1. Announce the release.
+   - IRC: #sequoia: "I released $VERSION of $PACKAGE"
+   - Signed email to `announce@lists.sequoia-pgp.org`,
+     `devel@lists.sequoia-pgp.org`, and optionally cc `lwn@lwn.net` if
+      there are particularly interesting changes.
+   - Blog post when the release contains interesting new stuff.