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.md34
1 files changed, 34 insertions, 0 deletions
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
new file mode 100644
index 0000000..945088d
--- /dev/null
+++ b/docs/guides/federation/upgrades.md
@@ -0,0 +1,34 @@
+# Upgrades and the federation's number
+
+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), Changing the federation).
+
+## Upgrading continuum
+
+A node of a federated swarm upgrades as any node does
+([`operations.md`](../../operations.md), Upgrading): one at a time, restarted with its
+files. Across a change of the wire format, 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. Until 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
+
+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`).
+
+There is one federation, 1. A node knows it alone: a version naming another is none to
+it, refused where a version event names it, with everything built on it. 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.