aboutsummaryrefslogtreecommitdiffstats
path: root/docs/operations.md
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/operations.md
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/operations.md')
-rw-r--r--docs/operations.md22
1 files changed, 19 insertions, 3 deletions
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