> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Content type: notice

> The published contract for time-bound network notices, including required persona impacts, actions, timing, and a copy-paste template.

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](/op-stack/contribute/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:

```yaml theme={null}
---
title: <Change or action>
description: <One sentence naming the change and affected readers.>
diataxis: reference
lang: en-US
content_type: notice
topic: <unique-kebab-case-topic>
personas:
  - <persona from keywords.config.yaml>
categories:
  - <category from keywords.config.yaml>
is_imported_content: 'false'
---
```

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.

## 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 and move its navigation entry.
3. Record the permanent outcome in the
   [network upgrade registry](/op-stack/protocol/network-upgrades), using
   the [contract upgrades table](/op-stack/protocol/network-upgrades#contract-upgrades)
   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:

```mdx theme={null}
---
title: <Change or action>
description: <One sentence naming the change and affected readers.>
diataxis: reference
lang: en-US
content_type: notice
topic: <unique-kebab-case-topic>
personas:
  - <affected-persona>
categories:
  - <approved-category>
is_imported_content: 'false'
---

<One or two paragraphs: what is changing, who must act, and the activation
mechanism or known date.>

## Why this is changing

<The user-facing motivation. Link the durable explanation or specification
for deeper context.>

## What's included

*   <Change in scope>
*   <Change in scope>

This change does not <important exclusion>.

## Breaking Changes

### <Persona>

<What breaks or changes for this persona. State "No action is required" when
that is the result, then explain why.>

### <Persona>

<Impact and compatibility details for the next persona.>

## Required actions

| Component or integration | Required change |
| --- | --- |
| `<name>` | <Version, flag, API, contract, or workflow change> |

<Add a short action checklist or link the canonical runbook.>

## Timing

<Activation date or mechanism. Say whether the change includes a hardfork.
Name the canonical source where final timestamps or releases will appear.>

## Verify readiness

*   <Observable check and expected result>
*   <Observable check and expected result>

For support, <link the issue tracker or support channel>.
```