Skip to main content
A notice tells affected readers about an upcoming network upgrade, deprecation, or operational change and gives them the actions required to stay compatible. Notices are time-bound: they remain active while readers need to prepare, then move to the notice archive after the change is complete. This page is the contract for the type. Review a new notice against it and cite the relevant section instead of re-arguing the structure in each pull request.

​
Composition

A notice is diataxis: reference: it gives readers authoritative facts about one change, including its scope, compatibility, timing, and affected versions. Put the executable migration procedure in a how-to guide or runbook and link it from the notice. The additional content_type: notice metadata key (with an underscore) marks the page’s operational purpose and lifecycle. It is not a fifth Diátaxis quadrant or one of the composed documentation types. The similarly named content-type: key (with a hyphen) remains reserved for the four compositions in Choose a content type.

​
Purpose

  • Name the change, why it is happening, and when it takes effect.
  • Identify every affected persona and state the breaking changes or explicit no-action outcome for each one.
  • Give readers an action checklist with versions, configuration, contract, or application changes they can verify before the cutover.
  • Preserve the transition behavior readers need to know, such as what happens to in-flight withdrawals, disputes, or transactions.
Do not use a notice as the permanent explanation of a feature or the only record of an upgrade. Link canonical guides and reference pages for durable details.

​
Required frontmatter

Every notice carries the metadata used by the notice index and site search:
Use every applicable persona from keywords.config.yaml; do not reduce the list to the primary audience. Add audit-source: when source files or generated artifacts were checked to substantiate the notice. Add date: (an ISO YYYY-MM-DD value) when the notice is archived. It records the date the change took effect — the mainnet hardfork activation, the end-of-support date, the mainnet execution date of a contract upgrade, or the start of a time-boxed experiment — and it must match the row for the page in the notice archive. Omit the key rather than guess: when no canonical in-tree source gives a date, the archive row says “Not dated” instead.

​
Required components

Every notice must include:
  1. Summary: one or two paragraphs naming the change, its scope, and the primary action.
  2. Motivation (## Why <change> or ## Why this is changing): the user-facing reason for the change, with links to durable explanations when more background is useful.
  3. Change scope (## What's included or ## What is changing): the concrete protocol, contract, component, or product changes. State important exclusions explicitly.
  4. Persona impacts (## Breaking Changes): one ### subsection for each persona in frontmatter. State what breaks, what must change, and what remains compatible. If a persona has no action, say so directly.
  5. Required actions: copy-pasteable configuration, version, contract, or application changes. Use a component table when several releases are involved.
  6. Timing: the activation mechanism and schedule. For a network upgrade, say whether it has a hardfork activation. Do not invent a timestamp or release version; add it when the canonical source is available.
  7. Verification and support: tell readers how to verify readiness and where to report a problem.
When a change affects state that can span the cutover, explain the transition. Common examples include Dispute Games already in progress, withdrawals already proved, transactions in flight, and old configuration that must remain temporarily available.

​
Writing rules

  • Lead with the action and affected reader, not the internal project history.
  • Use proper product and protocol names. Preserve command, flag, package, function, and component spelling in code formatting.
  • Separate confirmed scope from unknown timing or release data. Do not weaken confirmed changes by labeling the entire notice provisional.
  • Link to the canonical runbook or reference rather than duplicating its full procedure.
  • Keep persona subsections independently scannable. A reader should not need to infer their action from another persona’s section.

​
Lifecycle

Add an active notice to both /notices and the matching Network Notices navigation group in docs.json. After activation and completion of the required migration window:
  1. Move the page under /notices/archive.
  2. Remove its active card from /notices and delete its docs.json navigation entry. Archived notices are deliberately not in the sidebar: add the page to scripts/lint/nav-allowlist.json with a reason so the nav validator accepts it, set the page’s date: frontmatter, and add a row to the notice archive, which is how readers browse to it. The page keeps its URL forever — live pages link into it.
  3. Record the permanent outcome in the network upgrade registry, using the contract upgrades table when the change has no hardfork.
  4. Update durable guides and references so they describe the post-upgrade state without relying on the archived notice.

​
Template

Copy this template to start a notice: