Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
1 change: 1 addition & 0 deletions changelog.d/+cog-release.misc.md
Original file line number Diff line number Diff line change
@@ -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.
13 changes: 13 additions & 0 deletions cog.toml
Original file line number Diff line number Diff line change
@@ -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}}",
]
68 changes: 68 additions & 0 deletions tools/release-prepare
Original file line number Diff line number Diff line change
@@ -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
Loading