From 53d8d17d339df2e3e00e9627237ea5b4e1995cdc Mon Sep 17 00:00:00 2001 From: ComplexSpaces Date: Thu, 4 Jan 2024 02:36:24 -0600 Subject: [PATCH] Update release documentation and scripts to record flushed-out steps --- admin/RELEASING.md | 36 +++++++++++++++++++++++--------- ci/archive_android_release.sh | 39 +++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 10 deletions(-) create mode 100755 ci/archive_android_release.sh diff --git a/admin/RELEASING.md b/admin/RELEASING.md index dd5cf4ba..0e163c3b 100644 --- a/admin/RELEASING.md +++ b/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` - - * `--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 diff --git a/ci/archive_android_release.sh b/ci/archive_android_release.sh new file mode 100755 index 00000000..5186e3a5 --- /dev/null +++ b/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"