Network upgrade notes: announcing protocol changes you can’t deploy for anyone

A network upgrade — a blockchain hard fork, a federation-protocol version bump, a flag day, a wire-format change in a distributed system — is the one genre of release where publishing the software changes nothing. You tag the release and the network keeps running the old rules. The change happens later, at an activation moment, and only if enough operators — people you don’t employ, mostly can’t identify, and definitely can’t deploy for — act before it arrives. Everywhere else, release notes describe a change. Here they cause it: the notes are the coordination instrument, and writing them badly partitions the network.

The release is not the upgrade

Keep three events separate in your head and your writing: the software release (you control it), operator adoption (strangers control it), and activation (the clock or the chain controls it). Upgrade notes exist to move event two ahead of event three.

Activation moments come in three shapes. A block height or epoch number is deterministic on-chain and fuzzy on the calendar. A flag day is a fixed date after which old behavior is refused — rare and dreaded in internet infrastructure precisely because there is no negotiation. And version negotiation with a sunset: both protocol versions interoperate until a date, then the floor rises.

Whatever the shape, publish the moment in every representation you have. A height without a wall-clock estimate is unschedulable — nobody can book a maintenance window against “block 19,400,000”. A date without the height is false precision — block times drift. Give both, say which one is authoritative, and update the estimate as the moment approaches. Every serious blockchain upgrade announcement converges on the same line for a reason: “height N, currently estimated <date>.”

Three readers, three stakes

Node and server operators read the entry as a to-do with a deadline: minimum version, upgrade window, expected restart or resync cost, and whether rolling back is possible if the upgrade goes wrong (often it isn’t — say so, per the firmware guide’s rollback-is-not-a-given rule).

Builders on top — exchanges, wallets, indexers, bridges, bots, anyone whose software speaks to the network — read it as an interface diff: new fields, changed fee rules, deprecated RPC methods, altered semantics. They also need the testnet dates, because their rehearsal is your rehearsal: an upgrade that activates on a test network weeks early, with its own published height, is the single biggest gift you can hand this audience.

Everyone else — people who hold the asset, chat on the network, play the game — mostly needs reassurance. “If you use a hosted wallet or the official client with auto-update, you don’t need to do anything” is worth its line every single time it is true.

Say what happens to people who do nothing

This genre has a property almost no other release has: inaction has a cliff. An unupgraded node doesn’t just miss features — it keeps enforcing the old rules, forks onto a minority chain, stops syncing, or gets dropped by every upgraded peer. State the consequence plainly, early, and without euphemism: not as a threat, as physics. “Nodes below v1.9 will reject post-upgrade blocks and stop following the network” prevents the incident report that “please upgrade at your earliest convenience” guarantees.

Include the point of no return while you’re at it: the last safe moment to upgrade, and what a late operator faces — clean restart, full resync, or manual recovery. Operators triage their week off those two facts.

A campaign, not a post

One announcement cannot coordinate a network. The breaking-changes playbook’s announce-three-times floor is the minimum here; real upgrades run a calendar: an early announcement months out (what, why, rough window), the testnet activation with its own heights and dates, the firm mainnet date, reminders as adoption numbers come in, an activation-day entry, and — the one everybody forgets — a confirmation entry: “activated at height N; here’s how to check you’re on the right chain, and what to do if you’re not.” (The release-communication checklist generalizes this pattern.)

Between entries, signal in-band: recent node versions log an escalating countdown, peer-version dashboards make adoption public, and the warning in the log prints the announcement’s permalink — the operator who never reads your blog does read their own logs at 2am. Mirror every entry to chat as pointer, never archive.

Mixed-version windows: the federated cases

Not every network upgrade is a blockchain. Matrix bumps room versions, mail operators raise TLS floors, game studios revise multiplayer wire protocols, database clusters roll through mixed-version states during upgrades. These are gentler — negotiation instead of a cliff — but they add a deliverable the hard fork doesn’t have: the interoperability matrix. Which version pairs can talk, in which direction, until when. Publish it in the entry and keep it current; every support thread about a half-upgraded fleet starts with exactly that question.

And measure before you schedule: the long tail of any federation never upgrades on its own. Survey the live versions your peers actually run before choosing a floor, and when you finally cut the stragglers off, that’s a dropping-support announcement with everything it owes its readers.

Security upgrades: precise urgency, vague mechanism

A consensus bug or remotely-triggerable crash is the hardest version of the two-clocks problem: you need mass adoption fast, and the announcement that produces it is also a treasure map. The resolution is the same discipline turned up: be precise about urgency and versions, vague about mechanism. “Upgrade to v1.9.1 before height N; this release contains a consensus-critical fix; details published after activation” is legitimate here in a way it is almost nowhere else — adversaries diff releases within hours, so the details clock starts at adoption, not at disclosure. Emergency forks follow the hotfix playbook: stub at ship time, full account after. What is never legitimate is the silent consensus change — operators discovering they diverged on rules nobody announced is the worst failure this genre can produce.

Names coordinate — if they map to versions

Named upgrades are not marketing fluff in this genre; a fork name is a coordination handle that one support thread, four client teams, and every adoption dashboard can share. The release-naming rules apply, plus one that’s load-bearing: every entry that uses the name carries the name→version table, per client. In multi-client ecosystems, “Aurora” means client A >= 2.4.0, client B >= 1.19.2, client C >= 0.31 — and an announcement that names the upgrade without that table has told most operators nothing they can act on.

An upgrade entry template

Aurora upgrade activates at block 19,400,000 (est. 2026-09-03, ~15:00 UTC)
2026-08-05 · tag: breaking

What: Aurora raises the per-block data limit and removes the legacy
fee RPC. Full spec: <link>.

Act by activation — minimum versions:
  noded >= 2.4.0 · altclient >= 1.19.2
Upgrading takes a restart; no resync. Estimate updates weekly at
<permalink> as the height approaches.

If you do nothing: nodes below the minimum reject post-Aurora blocks
and stop following the network. Rejoining later requires v2.4+ and a
restart from a post-upgrade snapshot.

For integrators: eth_legacyFee removed (deprecated since May); block
headers gain a dataRoot field. Rehearse now — Aurora activated
on testnet at block 8,100,000 on 2026-08-02.

You run nothing yourself? Hosted wallets and auto-updating official
clients need no action.

Track adoption: <peer-version dashboard>.

Height and estimated date together, versions per client, the do-nothing consequence as physics, the testnet rehearsal already behind it, and the bystander released in one line — every reader exits at the first paragraph that answers them.

Six network upgrade anti-patterns

  • Announcing the release, not the activation. “v2.4.0 is out” with the height in paragraph nine. The date is the story; the software is the errand.
  • Height-only scheduling. Operators book maintenance windows in wall-clock time. Publish the estimate, update it, and say where the live countdown is.
  • Assuming everyone runs latest. Scheduling a two-week window because your nodes upgrade in an afternoon. Look at your peer-version telemetry first; the tail is longer than you think.
  • The buried cliff. “We recommend upgrading at your convenience” for a change that strands old nodes on a dead chain. Politeness that costs your operators an outage isn’t politeness.
  • Name-only announcements. The upgrade has a name, a logo, and a countdown site — and no per-client version table anywhere.
  • The silent consensus change. Even a “harmless” rule tweak shipped without an entry means some operator diverges without knowing divergence was possible. Nothing in this genre is ever too small to announce.

Running upgrade notes on Wakelog

Wakelog fits the campaign shape well: drafts plus scheduled publishing let you write the early announcement, the reminders, and the activation-day entry in one sitting and let the calendar fire them; permalinks are stable enough to print from a node’s log warning and paste into operator runbooks; the breaking and announcement tags separate the cliff from the chatter; and RSS and JSON feeds are exactly what downstream teams wire into the vendor-monitoring loops watching you. Your release job posts the entry with one curl at tag time. The honest boundary: Wakelog won’t count your network’s live versions or tell you when activation is safe — it’s where the announcement lives, and the URL your log warning prints.

Start your changelog — free   Next: firmware release notes →

Related guides

Last updated 2026-08-01 · All guides