diff options
| author | tv <tv@krebsco.de> | 2026-11-19 17:27:17 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 19:25:55 +0100 |
| commit | 180aba9ff89a4a294e284aa281d96adbcfe1b85b (patch) | |
| tree | 5cf9e1cc989e3f7fbab14347f40ec0ff06b3a655 | |
| parent | eeec08b8d15ac3c3301060c71772a664bd2a4685 (diff) | |
scripts/release: a release checked, said how it upgrades, committed and tagged
Releases were made by hand: a commit, a tag, and whatever one remembered
to check. `scripts/release [--dry-run] X.Y.Z` makes one:
1. the tree clean, notes under Unreleased in CHANGELOG.md, the version
later than the last v* tag's;
2. the version set in Cargo.toml and Cargo.lock (and the --version
example in operations.md), then `cargo quick`, `cargo sim` and
scripts/federation-check, stopping at the first that fails and
leaving the tree as it was;
3. this build's `continuum --version` against the last release's,
built in a cache of its own: node by node where their wire versions
meet and Automerge is the same, every node together where they don't
share one, which from 1.0.0 on it refuses but in a major release;
Automerge changed, no remake until every node runs it;
4. the Unreleased notes become the release's, headed by what it found;
the commit `release X.Y.Z`, tagged vX.Y.Z with that, what the build
speaks and knows, and the notes; and federation-<F>.<R> too where the
build knows a later revision than the last release.
It pushes nothing. With --dry-run it checks and prints what it would
write. docs/development.md says how releases are made.
| -rw-r--r-- | CHANGELOG.md | 5 | ||||
| -rw-r--r-- | docs/development.md | 29 | ||||
| -rwxr-xr-x | scripts/release | 184 |
3 files changed, 218 insertions, 0 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index db1aad2..2d531c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ it from the release before ([`docs/operations.md`](docs/operations.md), ## Unreleased +* `scripts/release` makes a release: it checks the tree, says from the last release's + wire versions, Automerge and revisions whether it rolls out node by node, and commits + and tags it, pushing nothing ([`docs/development.md`](docs/development.md), + [Releasing](docs/development.md#releasing); [`scripts/release`](scripts/release)). + * Automerge is pinned to exactly the version `Cargo.toml` names, so no rebuild changes what nodes must agree on unnoticed ([`docs/operations.md`](docs/operations.md), [Upgrading](docs/operations.md#upgrading); [`Cargo.toml`](Cargo.toml)). diff --git a/docs/development.md b/docs/development.md index 314ae11..39eabdf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -102,3 +102,32 @@ A node on several transports is a node on several simulated nets, one per scheme (`Sim::start_on`, under the identity layer): nodes on different nets can't reach each other, as one on Tor alone and one on libp2p alone can't, so a swarm whose transports don't all meet is simulated with the simulated transport alone. + +## Releasing + +A release is a commit `release X.Y.Z` tagged `vX.Y.Z`, and its version says how to +upgrade to it from the release before ([`operations.md`](operations.md), +[Upgrading](operations.md#upgrading)). `scripts/release` makes one, and pushes nothing: + +```sh +scripts/release --dry-run 0.0.2 # checks, and says what it would write +scripts/release 0.0.2 # the same, then commits and tags +git push origin HEAD v0.0.2 +``` + +It takes a clean tree with notes under Unreleased in [`CHANGELOG.md`](../CHANGELOG.md), and a +version later than the last release's. It sets the version in `Cargo.toml` (and +`Cargo.lock`), then runs `cargo quick`, `cargo sim` and `scripts/federation-check`, and +stops at the first that fails, leaving the tree as it was. It builds the last release, +and compares what the two say they are (`continuum --version`): + +* **wire versions**: where they share one, the release rolls out node by node; where + they don't, every node upgrades together, which from 1.0.0 on only a major release + may ask; +* **Automerge**: where it differs, nobody remakes until every node runs the release; +* **the federation's revisions**: a release knowing a later one than the last is + tagged `federation-<F>.<R>` too, so that later releases are checked against it. + +What it finds heads the release's notes in the change log and its tag's message, with +what the build speaks and knows, and the notes. Before 1.0.0 every upgrade may still be +taken as a flag day, but the notes say when it isn't. diff --git a/scripts/release b/scripts/release new file mode 100755 index 0000000..296766e --- /dev/null +++ b/scripts/release @@ -0,0 +1,184 @@ +#!/bin/sh +# Makes a release of continuum (docs/development.md: Releasing): checks this tree, says +# how it upgrades from the release before, and commits and tags it. It pushes nothing. +# +# scripts/release [--dry-run] VERSION +# +# VERSION is the release's, X.Y.Z, later than the latest v* tag. In order: +# +# 1. The tree is clean, CHANGELOG.md has notes under Unreleased, and VERSION is later +# than the last release. +# 2. Cargo.toml takes VERSION (and Cargo.lock with it), docs/operations.md's --version +# example too; then `cargo quick`, `cargo sim` and scripts/federation-check pass. +# 3. This build's `continuum --version` and the last release's (built in +# CONTINUUM_RELEASE_TARGET, ~/.cache/continuum/release unless set) say how one upgrades: +# node by node where their wire versions meet and their Automerge is the same, else +# every node together, which takes a major release from 1.0.0 on. +# 4. CHANGELOG.md's Unreleased notes become VERSION's, under a line saying so; the +# commit `release VERSION` holds it all, tagged vVERSION, its message saying how to +# upgrade, what the build speaks and knows, and the notes. A release knowing a later +# revision of the federation than the last is tagged federation-<F>.<R> too. +# +# With --dry-run, it checks and says what it would write; it, or a check failing, leaves +# the tree as it was. +# CONTINUUM_FEATURES are the features it builds with, a transport among them +# (federation,mycelium unless given). + +set -eu + +dry=false +if [ "${1:-}" = --dry-run ]; then + dry=true + shift +fi +if [ $# -ne 1 ]; then + echo "usage: scripts/release [--dry-run] VERSION" >&2 + exit 2 +fi +version=$1 +say() { echo "release: $*" >&2; } +die() { + say "$*" + exit 1 +} + +cd "$(git rev-parse --show-toplevel)" +features=${CONTINUUM_FEATURES:-federation,mycelium} +cache=${XDG_CACHE_HOME:-$HOME/.cache} +target=${CONTINUUM_RELEASE_TARGET:-$cache/continuum/release} + +# 1. What may be released. +echo "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || die "$version: not X.Y.Z" +[ -z "$(git status --porcelain)" ] || die "the tree isn't clean: commit or stash first" +git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1 || die "Cargo.lock isn't tracked" +last=$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-version:refname | head -n 1) +if [ -n "$last" ]; then + later=$(printf '%s\n%s\n' "${last#v}" "$version" | sort -V | tail -n 1) + [ "$later" = "$version" ] && [ "${last#v}" != "$version" ] || + die "$version isn't later than the last release, $last" +fi +notes=$(awk '/^## Unreleased/{on=1; next} /^## /{on=0} on' CHANGELOG.md | sed '/^$/d') +[ -n "$notes" ] || die "CHANGELOG.md has nothing under Unreleased: say what changed" + +work=$(mktemp -d) +committed=false +restore() { + git worktree remove --force "$work/last" >/dev/null 2>&1 || true + if ! $committed; then + git checkout -q -- Cargo.toml Cargo.lock CHANGELOG.md docs/operations.md + fi + rm -rf "$work" +} +trap restore EXIT +trap 'exit 130' INT TERM + +# 2. The version taken, and the checks. +current=$(sed -n 's/^version = "\(.*\)"$/\1/p' Cargo.toml | head -n 1) +sed -i "0,/^version = \"$current\"$/s//version = \"$version\"/" Cargo.toml +sed -i "s/^# continuum [0-9][0-9.]*$/# continuum $version/" docs/operations.md +say "cargo quick" +cargo quick >&2 +say "cargo sim" +cargo sim >&2 +say "scripts/federation-check" +scripts/federation-check >&2 +changed=$(git diff --name-only | sort | tr '\n' ' ') +case "$changed" in +"Cargo.lock Cargo.toml "* | "Cargo.toml "*) ;; +*) die "the checks changed more than the version: $changed" ;; +esac + +# 3. How it upgrades from the last release. +speaks() { + cargo run -q --features "$features" --bin continuum -- --version +} +here=$(speaks) +field() { echo "$1" | sed -n "s/^$2 //p" | head -n 1; } +here_wire=$(field "$here" "wire versions") +here_automerge=$(field "$here" automerge) +here_federation=$(echo "$here" | sed -n 's/^federation \([0-9]*\): .*/\1/p') +newest_revision() { + newest=$(echo "$1" | sed -n 's/^federation [0-9]*: //p' | grep -o 'revision [0-9]*' | + tail -n 1 | sed 's/revision //') + echo "${newest:-0}" +} +here_revisions=$(newest_revision "$here") +if [ -n "$last" ]; then + git worktree add -q --detach "$work/last" "$last" + there=$(cd "$work/last" && CARGO_TARGET_DIR=$target speaks) + there_wire=$(field "$there" "wire versions") + there_automerge=$(field "$there" automerge) + there_federation=$(echo "$there" | sed -n 's/^federation \([0-9]*\): .*/\1/p') + there_revisions=$(newest_revision "$there") + if [ -z "$there_wire" ]; then + rolls=false + why="$last doesn't say which wire versions it speaks" + else + set -- $here_wire + here_oldest=$1 here_newest=$3 + set -- $there_wire + there_oldest=$1 there_newest=$3 + if [ "$here_oldest" -le "$there_newest" ] && [ "$there_oldest" -le "$here_newest" ]; then + rolls=true + why="" + else + rolls=false + why="no wire version both speak ($last: $there_wire; this: $here_wire)" + fi + fi + if [ "$here_automerge" != "$there_automerge" ]; then + automerge_line="Automerge $there_automerge becomes $here_automerge: remake nothing until every node runs this release." + else + automerge_line="" + fi + if $rolls; then + upgrade="From $last it rolls out node by node: install it on every node, in any order." + else + upgrade="From $last every node upgrades together: $why." + major_last=$(echo "${last#v}" | cut -d. -f1) + major_here=$(echo "$version" | cut -d. -f1) + if [ "$major_last" -ge 1 ] && [ "$major_here" -le "$major_last" ]; then + die "$why: from 1.0.0 on, that takes a major release, not $version" + fi + fi +else + upgrade="The first release made by this script." + automerge_line="" + there_revisions=$here_revisions + there_federation=$here_federation +fi +revision_tag="" +if [ -n "$here_federation" ] && [ "${here_revisions:-0}" -gt "${there_revisions:-0}" ]; then + revision_tag="federation-$here_federation.$here_revisions" + revision_line="It knows revision $here_revisions of federation $here_federation: pass a version naming it once every party's nodes run this release." +else + revision_line="" +fi + +# 4. The notes, the commit and the tags. +date=$(date -u +%Y-%m-%d) +section=$(printf '%s\n' "$upgrade" "$automerge_line" "$revision_line" | sed '/^$/d') +awk -v version="$version" -v date="$date" -v section="$section" ' + /^## Unreleased/ && !done { + print; print ""; print "## " version " (" date ")"; print ""; print section + done = 1; next + } + { print } +' CHANGELOG.md >"$work/changelog" +cp "$work/changelog" CHANGELOG.md +message=$(printf 'continuum %s\n\n%s\n\n%s\n\n%s\n' "$version" "$section" \ + "$(echo "$here" | tail -n +2)" "$notes") + +if $dry; then + say "would commit 'release $version' and tag v$version${revision_tag:+ and $revision_tag}:" + echo "$message" + exit 0 +fi +git commit -q -m "release $version" -- Cargo.toml Cargo.lock CHANGELOG.md docs/operations.md +committed=true +git tag -a -m "$message" "v$version" +if [ -n "$revision_tag" ]; then + git tag -a -m "$revision_line" "$revision_tag" +fi +say "committed and tagged v$version${revision_tag:+ and $revision_tag}; nothing pushed:" +say " git show v$version; git push origin HEAD v$version${revision_tag:+ $revision_tag}" |
