diff options
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 34 | ||||
| -rw-r--r-- | docs/guides/federation/when-things-go-wrong.md | 11 |
3 files changed, 23 insertions, 24 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 5a44306..32f8756 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -31,7 +31,7 @@ by them, in its words. * [`remakes.md`](remakes.md): compactions only, the electorate, the snapshot, putting again after a switch, two epochs for one, and rejoining. * [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, and what the - federation's number says. + federation's number and its revision say. * [`watching.md`](watching.md): what a node's API and its log say that needs an operator or a party. * [`building-on-the-api.md`](building-on-the-api.md): an application reading what diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index df01b05..a106137 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -16,14 +16,14 @@ continuum's first release, take every upgrade as such a change. 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. -## The federation's number +## 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`): 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`). +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 @@ -32,16 +32,14 @@ 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. -A change to any of that is a federation of its own, with the next number, and its own -design. A swarm moves to it by a version naming it, which the parties pass once their -nodes run a continuum that knows it. +What is judged at an event's history changes by a revision of federation 1, which a +version names by its ID (`"revision": "<ID>"`); a version naming none follows the base +revision, `ecdsa-sha2-nistp256` keys beside Ed25519 ones among it. There are none yet but +the base revision. 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: roll it out first, every party's operators upgrading their nodes, then pass +a version naming it. -A change that only has the federation take what it refused, and reads nothing it took -otherwise, keeps the number: `ecdsa-sha2-nistp256` keys beside Ed25519 ones. Roll it out -first, then use it: every party's operators upgrade their nodes, and only then does a -party name such a key in a version or a key set, or sign with one. A node not upgraded -refuses what uses it and reads otherwise than the others; at a version naming such a key, -none to it, it stops, until it is upgraded. Nothing but agreement keeps a party from using -it early. The next such change names itself in the version, so that two thirds decide -when it is used: what it adds is taken only under a version naming it, and a node not -upgraded stops at that version. +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). diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md index fad11c5..8171201 100644 --- a/docs/guides/federation/when-things-go-wrong.md +++ b/docs/guides/federation/when-things-go-wrong.md @@ -78,13 +78,14 @@ can't judge`), and `GET /events` names the event, why, and how many it holds bac ```sh curl -s -u tv:secret localhost:3000/events | jq -r .stopped.why -# version 3c0f… passed, and doesn't read as one here: of federation 2, and this -# continuum knows 1 alone +# version 3c0f… passed, and doesn't read as one here: revision 9f2c…, which this +# continuum doesn't know, as it knows the base revision alone: a release that knows it +# reads this version ``` -`why` says what doesn't read: a federation this continuum doesn't know, a field it -doesn't know, by its name, a key of a type it doesn't take, or whatever else makes a -version none ([`proposing-and-voting.md`](proposing-and-voting.md), +`why` says what doesn't read: a federation or a revision this continuum doesn't know, a +field it doesn't know, by its name, a key of a type it doesn't take, or whatever else +makes a version none ([`proposing-and-voting.md`](proposing-and-voting.md), [Writing a version](proposing-and-voting.md#writing-a-version)). Upgrade the node to a continuum that reads it: restarted, it reads its store anew and |
