Skip to content

docs(contributing): add changelog reconcile-at-release rule #73

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
subkoks merged 1 commit into from
Jun 25, 2026
Merged

docs(contributing): add changelog reconcile-at-release rule #73

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
16 changes: 14 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,26 @@ After rule changes:
make check
```

## Changelog

- **Per PR:** user-visible changes add a `CHANGELOG.md` entry under `## [Unreleased]`, grouped `Added` / `Changed` / `Fixed` / `Removed` (Keep a Changelog style). Internal-only churn (CI tweaks, lint, refactors with no consumer-visible effect) does not need an entry.
- **Entries describe changes since the last release tag** — not work already shipped. Do not copy entries forward from a prior version's section.
- **At release time, reconcile before cutting.** `[Unreleased]` is a staging area that drifts: entries get duplicated from earlier sections, describe already-shipped work, or miss changes that landed without an entry. Before moving `[Unreleased]` into a dated `## [X.Y.Z]` section, reconcile it against the actual diff:

```bash
git diff <last-tag>..HEAD --stat # what actually changed
git log --oneline <last-tag>..HEAD # the commits behind it
```

Drop entries whose files are unchanged since `<last-tag>` (already shipped), add genuinely-new changes that have no entry, and verify each kept line matches the diff. The published release notes must faithfully match `git diff <last-tag>..HEAD`.
- Cutting a release: follow [docs/releasing.md](docs/releasing.md).

## Pull requests

- Use `.github/pull_request_template.md`.
- One logical change per PR; link pillar or issue when relevant.
- Include **test plan** (commands run, e.g. `make ci`).
- Run `make ci` (lint + check + skills-drift + test) before pushing.
- User-visible changes: add a `CHANGELOG.md` entry under `[Unreleased]` or the target version section.
- Cutting a release: follow [docs/releasing.md](docs/releasing.md).

## Security

Expand Down