From 9189649a78cccbb15329b9e1000e304bdd816eb4 Mon Sep 17 00:00:00 2001 From: "black.terminal" <64269417+subkoks@users.noreply.github.com> Date: Thu, 25 Jun 2026 19:21:28 +0100 Subject: [PATCH] docs(contributing): add changelog reconcile-at-release rule --- CONTRIBUTING.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 98fb487..4959f24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 ..HEAD --stat # what actually changed + git log --oneline ..HEAD # the commits behind it + ``` + + Drop entries whose files are unchanged since `` (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 ..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