Add a changeset

When to add one

Add a changeset when the PR changes user-visible contract behavior: a new function, a new contract or extension, a bug fix that changes outputs, a new event, a new error, a new interface ID, or a tighter requirement.

Skip for:

• NatSpec-only changes.
• Internal refactors with no observable effect.
• Test/mock-only changes.
• CI, lint, docgen, dependency bumps that don't change the published contracts/.

If unsure, err on the side of adding one — release reviewers can downgrade to "skip" by deleting the file before tagging.

How

npx changeset add

The CLI prompts for severity, then opens an editor. Severity:

• patch — bug fixes, gas optimizations, no API surface change.
• minor — new contracts, new extensions, new public functions on existing contracts.

There is no major from contributors — major version bumps are coordinated by maintainers.

The resulting file in .changeset/ looks like:

---
'openzeppelin-solidity': minor
---

`ComponentName`: One-sentence description starting with a backtick-quoted component name.

Format rules

• First word inside the backticks is the affected contract, extension, or library: ERC20, ERC1155Crosschain, Memory, Governor, etc.
• Then a colon, then one sentence describing the user-visible change.
• Imperative mood (matching PR titles: "Add", "Fix", not "Added", "Fixed"). Trailing period optional.
• No bullet points, no headings, no multi-paragraph prose. The release workflow concatenates these verbatim.
• State the change, don't justify it. Skip "This mirrors ...", "so that ...", "closes a gap where ...", parallels to other functions, or motivation. If the user needs to take action (migration step, breaking rename, tighter requirement they might now hit), state that instead — otherwise the changelog line is just the fact of the change. Rationale belongs in the PR body and commit message, not the changelog.

Good examples (taken from existing entries):

`Memory`: Add a `isReserved(Slice)` function that checks if the memory occupied by the slice is reserved (i.e. before the free memory pointer).

`ERC1155Crosschain`: Add an ERC-1155 extension to embed an ERC-7786 based crosschain bridge directly in the token contract.

Add ERC-165 detection for the `IERC6909ContentURI`, `IERC6909TokenSupply` and `IERC6909Metadata` interfaces in the `ERC6909ContentURI`, `ERC6909TokenSupply` and `ERC6909Metadata` contracts respectively.

(The last form — no leading backticks — is acceptable when several components are touched at once and a single prefix would be misleading.)

After committing

The changeset-bot GitHub check posts a comment confirming the changeset was detected. If the bot complains "No Changeset found" and the PR should not have one (NatSpec-only, etc.), leave a comment justifying it — a maintainer can apply the ignore-changeset label.