aboutsummaryrefslogtreecommitdiffstats
path: root/docs/development.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 17:27:17 +0000
committertv <tv@krebsco.de>2026-11-19 19:25:55 +0100
commit180aba9ff89a4a294e284aa281d96adbcfe1b85b (patch)
tree5cf9e1cc989e3f7fbab14347f40ec0ff06b3a655 /docs/development.md
parenteeec08b8d15ac3c3301060c71772a664bd2a4685 (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.
Diffstat (limited to 'docs/development.md')
-rw-r--r--docs/development.md29
1 files changed, 29 insertions, 0 deletions
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.