Skip to content

Migrate changelog from single file to directory structure #1552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sergey-shandar merged 1 commit into from
Aug 14, 2026
Merged

Migrate changelog from single file to directory structure #1552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 30 additions & 20 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,7 +331,7 @@ Where each kind of documentation belongs:
| ------------------------------------------------ | ----------------------------------------- |
| API shape and invariants | JSDoc on `module.f.*` exports or `types.ts` |
| Architectural choices, *why this / why not that* | the relevant `README.md` |
| What changed in a release | `CHANGELOG.md` (short, see §8.3) |
| What changed in a release | `changelog/` (short, see §8.3) |
| Rationale, measurements, alternatives considered | the PR description |

---
Expand Down Expand Up @@ -1219,11 +1219,17 @@ Ensure all of the checks in [§2](#2-everyday-workflow) pass.

### 8.3 CHANGELOG

To add a CHANGELOG entry, first open the PR to obtain its number, then add the
entry at the **top** of `## Unreleased` in [./CHANGELOG.md](./CHANGELOG.md) using
the real PR number. Follow the same `Topic: short description [#NNN](url)` style
as existing entries. New entries always go above existing ones. CHANGELOG entries
are created after the PR exists because they reference the PR number.
The changelog is the [./changelog/](./changelog/) directory, one file per
released version plus [./changelog/unreleased/](./changelog/unreleased/) holding
one file per unreleased PR — see
[changelog/README.md](./changelog/README.md) for the layout.

To add a CHANGELOG entry, first open the PR to obtain its number, then create
`changelog/unreleased/<PR>.md` named by that number. A PR never edits another
PR's file, so two PRs can never conflict. Follow the same
`Topic: short description [#NNN](url)` style as existing entries. A PR with
several entries puts them all in its one file, most important first. CHANGELOG
entries are created after the PR exists because they reference the PR number.

Only add CHANGELOG entries for code changes — PRs that only touch `todo/`,
`AGENTS.md`, or other documentation files do not need one.
Expand All @@ -1238,13 +1244,16 @@ Only add CHANGELOG entries for code changes — PRs that only touch `todo/`,
the pull request (`/pull/NNN`). Do not link to — or name in plain text — an
issue or `todo/` file: issue files are deleted when the work is done, so those
references rot and mean nothing to a reader of the published package.
- These two rules govern **new** entries. Don't rewrite a released section as a
side effect of an unrelated PR — a feature PR touches its own entry and nothing
else. A deliberate cleanup pass over past sections is a legitimate PR of its
own (this convention arrived as one), and no released text is lost when it
happens: each entry keeps its PR link, and the full prior wording stays in the
PR and in git history. Where an entry predates the convention and its PR cannot
be identified, leave it unlinked rather than guessing one.
- **A file holds list items only.** No heading — the version or PR number is the
file name — and no Markdown beyond paragraphs, list items, inline code, bold,
and links, so the website can render entries with a small self-hosted parser.
- These rules govern **new** entries. Don't rewrite a released version's file as
a side effect of an unrelated PR — a feature PR touches its own file and
nothing else. A deliberate cleanup pass over past releases is a legitimate PR
of its own (this convention arrived as one), and no released text is lost when
it happens: each entry keeps its PR link, and the full prior wording stays in
the PR and in git history. Where an entry predates the convention and its PR
cannot be identified, leave it unlinked rather than guessing one.

### 8.4 Breaking changes and versioning

Expand All @@ -1259,11 +1268,11 @@ Only add CHANGELOG entries for code changes — PRs that only touch `todo/`,
keeping a compatibility shim.
- **The project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
and the CHANGELOG decides which number moves.** A `**BREAKING CHANGES:**` entry
in `## Unreleased` means the release shipping it cannot be a patch. The package
is still pre-1.0, where the leading `0.` is pinned and the *minor* position
plays the role the major one plays after 1.0:
anywhere in `changelog/unreleased/` means the release shipping it cannot be a
patch. The package is still pre-1.0, where the leading `0.` is pinned and the
*minor* position plays the role the major one plays after 1.0:

| `## Unreleased` contains | Pre-1.0 — `0.Y.Z` | 1.0 and later — `X.Y.Z` |
| `changelog/unreleased/` contains | Pre-1.0 — `0.Y.Z` | 1.0 and later — `X.Y.Z` |
| ------------------------------------------- | ----------------- | ----------------------- |
| at least one `**BREAKING CHANGES:**` entry | `0.(Y+1).0` | `(X+1).0.0` |
| new features, nothing breaking | `0.Y.(Z+1)` | `X.(Y+1).0` |
Expand All @@ -1286,6 +1295,7 @@ Only add CHANGELOG entries for code changes — PRs that only touch `todo/`,
predate this convention and took a minor bump for feature-only releases too
(`0.35.0`, `0.33.0`); they are published, so leave their numbers alone.
- Releasing is its own commit: the version lives in `package.json` (`"version"`)
— `deno.json` holds tasks and formatting only. When it's bumped, create a new
`## X.Y.Z` section in `CHANGELOG.md` immediately after `## Unreleased` and move
all entries from `## Unreleased` into it, leaving `## Unreleased` empty.
— `deno.json` holds tasks and formatting only. When it's bumped, concatenate
every `changelog/unreleased/*.md` in descending PR-number order into a new
`changelog/X.Y.Z.md` and delete the entry files, leaving
`changelog/unreleased/` with only its `.gitkeep`.
Loading
Loading