Update release documentation and scripts to record flushed-out steps

Author: complexspaces

admin/RELEASING.md

@@ -1,7 +1,20 @@
 # How-to release `rustls-platform-verifier`
 
 This document records the steps to publish new versions of the crate since it requires non-trivial preparation and ordering
-that needs to be remembered due to the Android component's distribution.
+that needs to be accounted for due to the Android component's distribution.
+
+The Rustls repo also has [RELEASING] guidance for more information (e.g. on best practices for creating a GitHub release with a changelog)
+and other steps.
+
+In the release preparation PR, the releaser may include the following checklist in the description so post-merge actions can be tracked:
+```markdown
+### Post-merge steps
+
+- [ ] Generate Android Maven artifacts locally
+- [ ] Create and push Git tag
+- [ ] `cargo publish` for each required crate, based on release steps
+- [ ] Create companion GitHub release
+```
 
 ## Steps
 
@@ -14,21 +27,24 @@ that needs to be remembered due to the Android component's distribution.
         * We typically leave these branches around for future maintenance releases.
     4. Run `ci/package_android_release.sh` in a UNIX compatible shell
     5. (Optional) `cargo publish -p rustls-platform-verifier-android --dry-run --alow-dirty`
-        <!---
-        TODO: Consider instead making tag-specific commits that check-in the artifacts. For now, the 
-        seamless AAR reproducibility makes this a non-issue.
-        -->
-        * `--allow-dirty` is required because we don't check-in the generated Maven local repository at this time.
+        * `--allow-dirty` is required because we don't check-in the generated Maven local repository.
     6. (Optional) Inspect extracted archive to ensure the local Maven repository artifacts are present
         1. Un-tar the `rustls-platform-verifier-android-*.crate` file inside of `target/package`.
         2. Verify `maven/rustls/rustls-platform-verifier` contains a single `*.RELEASE` directory and that contains a `.aar` file.
         3. (Optional) If the releaser has an external Gradle project that uses the configuration from the README, paste the path to the
            unzipped package's `Cargo.toml` as a replacement for the `manifestPath` variable. Run a Gradle Sync and observe everything works.
-    7. Publish the Android artifacts' new version: `cargo publish -p rustls-platform-verifier-android --alow-dirty`
+    7. **Ensure that all version changes are committed to the correct branch before proceeding**. All version increases should be checked in prior
+       to publishing on crates.io.
+    8. Publish the Android artifacts' new version: `cargo publish -p rustls-platform-verifier-android --alow-dirty`
+
 3. Commit main crate's version increase on the release branch
-4. Publish the main crate's new version: `cargo publish -p rustls-platform-verifier`
+4. **Ensure that all version changes are committed to the correct branch before proceeding**. All version increases should be checked in prior
+    to publishing on crates.io.
+5. Publish the main crate's new version: `cargo publish -p rustls-platform-verifier`
     * Do **not** use `--allow-dirty` for the main crate. Only the Android component requires it and a dirty workspace elsewhere is an error.
-
-See the Rustls repo [RELEASING] guidance for more information (e.g. on best practices for creating a GitHub release with a changelog).
+6. Follow the remaining steps in [RELEASING] to create the appropiate version tag.
+7. If a new Android component release was made: Before publishing the GitHub release, run `./ci/archive_android_release.sh` to create a reproducible archive
+   containing the Android Maven components that were just published to crates.io. After creating the archive, upload it as an additional release artifact on GitHub.
+   Then, finish the release creation like normal.
 
 [RELEASING]: https://github.com/rustls/rustls/blob/main/RELEASING.md

ci/archive_android_release.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+# This script's purpose is to package up the Android-specific artifacts from a previous run of `cargo publish -p rustls-platform-verifier-android` for
+# later attachment to GitHub releases. It is also intended to be fully reproducible.
+
+set -euo pipefail
+
+TAR_NAME="tar"
+OUTPUT_NAME="android-artifacts.tar"
+version=$(grep -m 1 "version = " android-release-support/Cargo.toml | tr -d "version= " | tr -d '"')
+source_date_epoch=$(git log -1 --pretty=%ct)
+
+# bsdtar (which is the default on macOS) doesn't support the flags we want, so attempt to find a version of GNU
+# tar on the system is possible.
+if $TAR_NAME --version | grep -q "bsdtar"; then
+    echo "Detected bsdtar, which is not compatible with this script. Attempting 'gnutar'"
+    TAR_NAME="gnutar"
+
+    if $TAR_NAME --version | grep -q "bsdtar"; then
+        echo "GNU tar not found, exiting"
+        exit 1
+    fi
+fi
+
+artifacts_dir="target/package/rustls-platform-verifier-android-$version"
+
+# This differs based on host target, etc.
+rm -rf "$artifacts_dir/target"
+# This shows up a lot on macOS, so make sure it doesn't get in the way.
+rm -f "$artifacts_dir/.DS_Store"
+
+# Ref: https://reproducible-builds.org/docs/archives/
+$TAR_NAME --sort=name \
+    --mtime="@${source_date_epoch}" \
+    --owner=0 --group=0 --numeric-owner \
+    --pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime \
+    -cf "$artifacts_dir/../$OUTPUT_NAME" -C "$artifacts_dir" .
+
+echo "Successfully created tarball at $artifacts_dir/$OUTPUT_NAME"