# Upgrades and the federation's revisions Upgrading the continuum a federated swarm's nodes run, what the federation's number and its revision in each version say, and moving to a later revision. The rules are the design's ([`federation.md`](../../federation.md), [Changing the federation](../../federation.md#changing-the-federation)). ## Upgrading continuum A node of a federated swarm upgrades as any node does ([`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. 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 What every node must agree on, byte for byte, is named by the federation's number, which every version gives (`"federation": 1`), and its revision: the rules, how an event, a version and a checkpoint are spelled, signed and judged, what the events read as, and, on Automerge, what the document holds, what a change writes, the genesis change built from the root, the snapshot, and the Automerge version, whose encoding fixes a change's hash. Their bytes are fixed by vectors that the tests check (`federation::vectors`). There is one federation, 1. A node knows it alone: a version naming another is none to it. Where one passes, the node stops at the version event writing it, taking nothing and refusing nothing, until it runs a continuum that knows it, or its operator has it drop that event ([`when-things-go-wrong.md`](when-things-go-wrong.md), [A node stopped](when-things-go-wrong.md#a-node-stopped)). A proposal naming another is taken as a proposal, and a party's client backs none. What is judged at an event's history changes by a revision of federation 1, which a version names by its ID (`"revision": ""`); a version naming none follows the base revision, `ecdsa-sha2-nistp256` keys beside Ed25519 ones among it. Each later revision adds a feature to the one before; `federation.md` lists them ([Changing the federation](../../federation.md#changing-the-federation)). A node that doesn't know the revision a version names reads it as it reads one of another federation: none, and it stops at a version event writing it. What a revision adds is taken only under a version naming it, which two thirds pass, so no party uses it early. What no history judges, the document, a change and the snapshot, no version names: a change there splits the swarm until every node runs it (above). ## Moving to a revision First every node runs a continuum that knows the revision, then the parties pass a version naming it. Restarting the nodes changes nothing in the swarm: what the revision adds is refused everywhere until a version names it. 1. **Upgrade.** Each party's operators restart every node of the party on such a continuum. A node says which revisions it knows: ```sh curl -s -u tv:secret localhost:3000/events | jq -r '.revisions[].named' # the base revision # revision 1 (merge-events) ``` and the revision of the current version, in `GET /events/counts` (`.version.revision.named`). There too, of each node the parties list, the newest revision it said it knows (`knows`; [`peers.md`](../../peers.md), [Handshake and join](../../peers.md#handshake-and-join)), as far as this node heard from it: the nodes still to upgrade, every party's. ```sh curl -s -u tv:secret localhost:3000/events/counts | jq -r '.parties | to_entries[] | .key as $party | .value.knows | to_entries[] | "\($party) \(.key): \(.value.revision.named // "said nothing")"' # lass continuum:9c07…: the base revision # tv continuum:5be1…: revision 1 (merge-events) # tv continuum:77d3…: said nothing ``` A node says nothing on a build from before it said this, or where this node didn't hear from it since it started: each says it with each handshake. 2. **Propose.** A party begins the next version following it, by the feature it adds; `next` says so where its node knows a later revision than the current version's: ```sh continuum-party --node http://tv:secret@localhost:3000 next --revision merge-events \ > next.json continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ --record tv.record propose next.json # proposal 5e81… ``` Where nodes the parties list aren't known to know the revision, `next` warns, and names them. It may already hold what the revision adds to a version: a version is read by the revision it names. Its proposal and the votes on it are judged under the current version, and what the revision adds to events counts from the version after. 3. **Vote.** Each party backs it once every node of the party knows the revision: ```sh continuum-party --node http://tv:secret@localhost:3000 proposals # 5e81…: can still pass; true: tv; false: nobody # changes: "1f4c…" -> "8a20…" # number: 4 -> 5 # revision: the base revision -> revision 1 (merge-events), 6c1d… continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ --record tv.record vote 5e81… yes ``` The client backs it only where its node knows the revision, and says so otherwise. It backs it where other nodes, of any party, aren't known to know it, and warns, naming them and what each said (`knows`, above): once it passes, those stop at it till upgraded. ``` Warning: these nodes aren't known to know revision 1 (merge-events), as far as the node heard from them; once a version of it passes, each stops at it till upgraded: tv: continuum:77d3… said nothing: a build from before SPEAKS, or not heard from ``` A node voting by itself backs no version changing the revision: vote on it by hand, through that node. A party not ready leaves it be, or votes `false` to end it. 4. **After.** Once two thirds passed it, what the revision adds counts from that version on. A node that doesn't know it stops at that version (`stopped` in `GET /events`, [`when-things-go-wrong.md`](when-things-go-wrong.md), [A node stopped](when-things-go-wrong.md#a-node-stopped)), takes nothing and votes nothing until upgraded, and reads its store anew once restarted on a continuum that knows it.