aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 13:41:35 +0000
committertv <tv@krebsco.de>2026-11-19 14:44:10 +0100
commit3b4d0cc4f167ca77d74110cb59c9c85276723965 (patch)
treee471f306b1e85fbedb47b75434ee31798ef7f703 /docs
parent9164ebfe9a4014cbbaaaff90c5a1d722e39457fd (diff)
docs: what a release's version says of upgrading to it
A release is tagged v<version>, and its version says, from the operator's side, how to upgrade to it from the release before: a patch one node at a time, fixes only (a fix to what the federation judges comes as a revision); a minor one node at a time still, adding to the API or bringing a revision the parties then pass; a major one every node close together, a flag day: no wire version both releases speak, a document, change or snapshot built otherwise, files the node can't restart with, the API or continuum-party changed other than by adding, or a new federation. Before 1.0.0 any release may be a flag day, and its tag's message says whether it is. operations.md and the federation's upgrades guide say so; a node speaking one wire version, every change of the format is a major release. architecture.md said wire formats grow by appending so that a swarm upgrades node by node, which no build does: every change bumps the version, and builds tell each other apart instead.
Diffstat (limited to 'docs')
-rw-r--r--docs/architecture.md7
-rw-r--r--docs/guides/federation/upgrades.md20
-rw-r--r--docs/operations.md22
3 files changed, 35 insertions, 14 deletions
diff --git a/docs/architecture.md b/docs/architecture.md
index 202495d..f70f132 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -288,8 +288,11 @@ places that rely on it.
* **Conflicts are errors; overrides are named.** A contradiction in the configuration
or at the API refuses with a message that names the `force` value that would
override it, in one camelCase vocabulary everywhere.
-* **Wire formats grow by appending.** New fields default when absent, so a swarm can
- be upgraded one node at a time (until the first release lifts that constraint).
+* **Builds tell each other apart.** Every change of the wire format bumps its version,
+ and a node ignores messages of another version instead of misreading them: across a
+ change, the swarm is split until every node runs it, and merges then. A release's
+ version says whether it is such a change ([`operations.md`](operations.md),
+ [Upgrading](operations.md#upgrading)).
## Where the complexity sits
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index 55dd921..f6964a6 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -8,16 +8,18 @@ design's ([`federation.md`](../../federation.md),
## Upgrading continuum
A node of a federated swarm upgrades as any node does
-([`operations.md`](../../operations.md), [Upgrading](../../operations.md#upgrading)): one
-at a time, restarted with its files. Across a change of the wire format, upgraded nodes
-and the others don't talk, and the swarm is split until all are upgraded; a remake needs
-the same Automerge on every node, and one with another rejoins instead of switching. Until
-continuum's first release, take every upgrade as such a change.
+([`operations.md`](../../operations.md), [Upgrading](../../operations.md#upgrading)),
+restarted with its files, and a release's version says how: a patch or a minor release one
+node at a time, a major one every node close together. Across a change of the wire
+format, a major one, upgraded nodes and the others don't talk, and the swarm is split
+until all are upgraded; a remake needs the same Automerge on every node, and one with
+another rejoins instead of switching. Before 1.0.0, take every upgrade as a major one.
-Nobody runs every node of a federated swarm: each party's operators upgrade its nodes.
-Agree on when, among the parties, and upgrade close together. Which wire versions each
-node the parties list speaks, as far as a node heard from it, shows in
-`GET /events/counts` (`knows`, below: `wire`, the oldest and the newest).
+Nobody runs every node of a federated swarm: each party's operators upgrade its nodes. A
+patch or minor release each party takes when it likes; for a major one, agree on when,
+among the parties, and upgrade close together. Which wire versions each node the parties
+list speaks, as far as a node heard from it, shows in `GET /events/counts` (`knows`,
+below: `wire`, the oldest and the newest).
## The federation's number and its revision
diff --git a/docs/operations.md b/docs/operations.md
index 4b42992..0502782 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -93,7 +93,23 @@ file: the same swarm again, empty), and the others join it
## Upgrading
-One node at a time, restarting each with its files. What to know:
+A release is tagged `v<version>`, and its version ([semver](https://semver.org)) says
+how to upgrade to it from the release before:
+
+* **Patch** (`1.0.1`): one node at a time; it only fixes. A fix to what the federation
+ judges comes as a revision, in a minor release.
+* **Minor** (`1.1.0`): one node at a time still. It may add to the API, or bring a
+ revision of the federation, which the parties pass once every node runs it
+ ([`guides/federation/upgrades.md`](guides/federation/upgrades.md)).
+* **Major** (`2.0.0`): every node close together, a flag day. Its nodes and those of the
+ release before can't work together (no wire version both speak, or a document, a change
+ or a snapshot built otherwise), or a node can't restart with the files the release
+ before left, or the API or `continuum-party` changes other than by adding, or it makes
+ a new federation.
+
+Before 1.0.0, any release may be a flag day; its tag's message says whether it is.
+
+A node upgrades by restarting with its files. What to know:
* **The wire format.** Each change to it bumps a version byte, and nodes ignore
messages of another version. Across such a change, upgraded nodes and the others
@@ -105,8 +121,8 @@ One node at a time, restarting each with its files. What to know:
[Handshake and join](peers.md#handshake-and-join)); a build from before SPEAKS logs it
as that warning, `version=0`, once of the peer, and reads the peer's other messages
where they are of its version.
- Until the first release, assume every upgrade is such a change, and upgrade all nodes
- close together.
+ A node speaks one version, so every change of the format is a major release; before
+ 1.0.0, take every upgrade as one, and upgrade all nodes close together.
* **Automerge.** A remake needs every node to build the same snapshot, byte for byte,
so the same Automerge version everywhere; a node with another one rejoins instead of
switching ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). Don't remake while