diff --git a/RELEASING.md b/RELEASING.md index d3254fe..a44ef29 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -9,20 +9,31 @@ Release builds are reproducible: the same commit built with Zig 0.17.1 gives byte-identical binaries, so anyone can check a published binary by building the tag and comparing the sha256. -## Checklist +`cog bump` does the mechanical part. `cog.toml` runs `tools/release-prepare` +before the bump commit; the script's header lists what it sets and what it +leaves to a person. -1. `version` in `src/main.zig` and `.version` in `build.zig.zon` name the new - version. -2. `README.md` and `COMPAT.md` describe this version; a new deliberate - difference from the shell script has its row in `COMPAT.md` and its label - in `tests/differential.sh`. -3. CI on `main` is green, both architectures. -4. Tag and push: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. -5. Check the draft release: two binaries, `SHA256SUMS`, attestations +## Steps + +1. Branch from `main`: `git switch -c chore/release-X.Y.Z origin/main`. +2. Edit, in a commit of its own, the prose the hook leaves alone: the README + sentence on what `main` has that the latest release lacks, the + "Release X.Y.Z runs ..." rows of `docs/orgmode/howto/install.org`, the + `--version` example of `docs/orgmode/reference/cli.org`, and a row in + `COMPAT.md` with its label in `tests/differential.sh` for each new + deliberate difference from the shell script. +3. `cog bump --minor` (or `--patch`, `--major`, `--version X.Y.Z`). It runs + the hook, commits `chore(version): X.Y.Z` and creates the tag on that + commit. `cog bump --minor --dry-run` prints the version only. +4. Push the branch, open the pull request, and merge it with a merge commit + once its checks pass, so the tagged commit is on `main`. +5. Sign the tag and push it: + `git tag -s -f vX.Y.Z -m "eb-keep-logs X.Y.Z" 'vX.Y.Z^{}' && git push origin vX.Y.Z`. +6. Check the draft release: two binaries, `SHA256SUMS`, attestations (`gh attestation verify FILE --repo stackhands/eb-keep-logs`). -6. Build the tag locally with `zig build -Drelease=true -Dcommit=<7-char sha> +7. Build the tag locally with `zig build -Drelease=true -Dcommit=<7-char sha> -Dtarget=x86_64-linux-musl` and compare its sha256 with `SHA256SUMS`. -7. Publish the draft. -8. Where a site keeps an EasyBuild recipe for eb-keep-logs (none is +8. Publish the draft. +9. Where a site keeps an EasyBuild recipe for eb-keep-logs (none is published), update it: version and the checksum of each binary from `SHA256SUMS`, then test-install it. diff --git a/changelog.d/+cog-release.misc.md b/changelog.d/+cog-release.misc.md new file mode 100644 index 0000000..8461450 --- /dev/null +++ b/changelog.d/+cog-release.misc.md @@ -0,0 +1 @@ +A release is cut with `cog bump`: `cog.toml` runs `tools/release-prepare`, which builds the changelog and sets the version wherever the release workflow or a download command names it. `RELEASING.md` has the steps. diff --git a/cog.toml b/cog.toml new file mode 100644 index 0000000..5f2bf1a --- /dev/null +++ b/cog.toml @@ -0,0 +1,13 @@ +# `cog bump --minor` (or --patch, --major, --version X.Y.Z) on a release branch: +# the hook below prepares the tree, cog commits it as `chore(version): X.Y.Z` +# and creates the tag vX.Y.Z on that commit. RELEASING.md has the steps around it. +tag_prefix = "v" +ignore_merge_commits = true +# CHANGELOG.md is not cog's to write; tools/release-prepare says who writes it. +disable_changelog = true +# A release is cut from a branch that becomes a pull request to main. +branch_whitelist = ["chore/release-*"] + +pre_bump_hooks = [ + "tools/release-prepare {{version}}", +] diff --git a/tools/release-prepare b/tools/release-prepare new file mode 100755 index 0000000..d978419 --- /dev/null +++ b/tools/release-prepare @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# Prepare the tree for a release: the pre-bump hook of cog.toml. +# +# usage: tools/release-prepare NEW_VERSION +# +# `cog bump` runs this with the version it is about to tag, then commits what +# changed and creates the tag. For NEW_VERSION and the version build.zig.zon +# still names (OLD) it sets: +# - CHANGELOG.md: `towncrier build` writes the fragments of changelog.d/ +# under a heading for NEW_VERSION and removes them; +# - build.zig.zon and src/main.zig: the version, which the release workflow +# compares with the tag; +# - README.md, docs/orgmode/howto/install.org and the tutorial: the latest +# tag, the download commands and the `--version` line. +# +# Not done here, because it is prose: the README sentence on what `main` has +# that the latest release lacks, the "Release X.Y.Z runs ..." rows of +# install.org, the `--version` example with a commit in +# docs/orgmode/reference/cli.org, and a COMPAT.md row for each new deliberate +# difference from the shell script. Edit those in a commit before the bump. +# +# Needs: towncrier (or uvx). A refused run can leave +# edited files behind; `git checkout -- .` puts the tree back. +set -euo pipefail + +new=${1:?usage: tools/release-prepare NEW_VERSION} +cd "$(dirname "${BASH_SOURCE[0]}")/.." + +die() { echo "release-prepare: $*" >&2; exit 2; } + +# set_in FILE SED_EXPRESSION...: edit FILE, and refuse a FILE the expressions +# leave unchanged, so a version string that moved fails the bump instead of +# being skipped. +set_in() { + local file=$1 before + shift + before=$(sha256sum < "${file}") + sed -i -E "$@" "${file}" + [ "${before}" != "$(sha256sum < "${file}")" ] || die "${file} does not name ${old} where expected" +} + +[[ ${new} =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "'${new}' is not X.Y.Z" +old=$(sed -n 's/^ *\.version = "\([0-9.]*\)",$/\1/p' build.zig.zon) +[ -n "${old}" ] || die "build.zig.zon names no version" +[ "${old}" != "${new}" ] || die "build.zig.zon already names ${new}" +old_re=${old//./\\.} + +if command -v towncrier > /dev/null 2>&1; then + towncrier build --version "${new}" --yes +else + uvx towncrier build --version "${new}" --yes +fi + +set_in build.zig.zon "s/^( *\.version = )\"${old_re}\",\$/\1\"${new}\",/" +set_in src/main.zig "s/^(pub const version = )\"${old_re}\";\$/\1\"${new}\";/" +set_in README.md \ + -e "s/(The latest tag is v)${old_re}\./\1${new}./" \ + -e "s/^(v=)${old_re}( arch=)/\1${new}\2/" +set_in docs/orgmode/howto/install.org \ + -e "s/^(Release v)${old_re}( is the latest tag)/\1${new}\2/" \ + -e "s/(v=)${old_re};/\1${new};/" \ + -e "s/(eb-keep-logs-)${old_re}(-[a-z0-9_]+-linux-musl)/\1${new}\2/" \ + -e "s/^(eb-keep-logs )${old_re}( \()/\1${new}\2/" +set_in docs/orgmode/tutorials/keep-a-failed-build-log.org \ + "s/^(eb-keep-logs )${old_re}( \()/\1${new}\2/" + +echo "release-prepare: ${old} -> ${new}" +git status --short | awk '{print $1}' | sort | uniq -c