diff options
| author | tv <tv@krebsco.de> | 2026-11-19 13:41:35 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 14:44:10 +0100 |
| commit | 3b4d0cc4f167ca77d74110cb59c9c85276723965 (patch) | |
| tree | e471f306b1e85fbedb47b75434ee31798ef7f703 /docs | |
| parent | 9164ebfe9a4014cbbaaaff90c5a1d722e39457fd (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.md | 7 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 20 | ||||
| -rw-r--r-- | docs/operations.md | 22 |
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 |
