aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/upgrades.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation/upgrades.md')
-rw-r--r--docs/guides/federation/upgrades.md76
1 files changed, 67 insertions, 9 deletions
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index a106137..0a1a094 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -1,7 +1,8 @@
-# Upgrades and the federation's number
+# Upgrades and the federation's revisions
-Upgrading the continuum a federated swarm's nodes run, and what the federation's number
-in each version says. The rules are the design's ([`federation.md`](../../federation.md),
+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
@@ -34,12 +35,69 @@ 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": "<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.
+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`).
+
+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…
+ ```
+
+ 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
+ can't see the party's other nodes, which its operators check. 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.