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.md43
1 files changed, 35 insertions, 8 deletions
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index 0a1a094..55dd921 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -15,7 +15,9 @@ the same Automerge on every node, and one with another rejoins instead of switch
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.
+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
@@ -61,7 +63,22 @@ adds is refused everywhere until a version names it.
```
and the revision of the current version, in `GET /events/counts`
- (`.version.revision.named`).
+ (`.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:
@@ -74,8 +91,9 @@ adds is refused everywhere until a version names it.
# 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
+ 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:
@@ -90,10 +108,19 @@ adds is refused everywhere until a version names it.
--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.
+ 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`,