From 3b4d0cc4f167ca77d74110cb59c9c85276723965 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 13:41:35 +0000 Subject: docs: what a release's version says of upgrading to it A release is tagged v, 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. --- docs/architecture.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/architecture.md') 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 -- cgit v1.3.1