# Changelog fragments

Add one Markdown file for each PR with a notable change. Feature branches add
fragments here; release-preparation branches assemble `CHANGELOG.md`.

Name the file `<PR>.<type>.md`, for example `1234.fix.md`. Use the PR number;
several PRs may address the same issue. Choose one type:

| Type | Content |
| --- | --- |
| `feature` | New capability. |
| `fix` | Corrected behaviour. |
| `change` | Changed behaviour, tooling or development workflow. |
| `removal` | Removed capability or compatibility. |
| `security` | Security improvement. |

Write concise British English describing the outcome and any required upgrade
action. Use ordinary Markdown prose without a heading or an outer bullet;
Towncrier adds the category, bullet and PR link. A fragment may contain several
paragraphs when the PR needs them.

For example, `1234.fix.md` could contain:

```md
Retry realtime connections when authorisation expires during owner reads,
restoring automatic navigation after sign-in.
```

Before a PR number is available, use a unique name such as
`+realtime-authorisation-retry.fix.md`. Rename it to the PR number before merging
when available. Fragments retained with a `+` name render without a PR link.
Keep one fragment per PR or unique name.

Validate with:

```sh
pnpm changelog:check
```

CI runs the same validation in its always-run policy group. It checks every
fragment's name and content, including on a release branch with no remaining
fragments. Whether a change warrants a release note is part of review.

For an existing PR that edits `CHANGELOG.md`, move only that PR's new notes into
its fragment and restore the changelog to the target branch's version when
updating the branch. Preserve notes already on the target branch.

See [release preparation](../docs/platform-releases.md#changelog-preparation)
for previewing and consuming fragments.