From f6f820a648e32b736f69bafe56c720dde92fcdab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Tue, 15 Sep 2026 21:59:27 +0000 Subject: [PATCH] :memo: Require a changelog note before finishing a branch A merged branch must carry a final commit adding a short summary of the work under [Unreleased] in CHANGELOG.md. create:release derives the bump heuristic from that body, so notes have to exist before release day; rationale in development/workflow.md. --- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 10 ++++++++-- development/workflow.md | 30 ++++++++++++++++++++++++++++++ 3 files changed, 40 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf85a65..02dcded 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +- require a short summary under `[Unreleased]` in the changelog before a branch is finished + ## [0.1.6] - 2026-09-15 - restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04cdfb6..753b2e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -164,6 +164,10 @@ reaches for by default: - **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (why: [development/publishing.md](./development/publishing.md#ci-only-publishing)) +- **A branch ends with a changelog note:** before `npm run create:finish`, + summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md). + (why: + [development/workflow.md](./development/workflow.md#changelog-notes)) - **A decision or its rationale belongs in `development/`, not here.** This file holds the actionable rule; `development/.md` holds why, the rejected alternatives and the known issues. When you change a rule, update its category @@ -204,9 +208,11 @@ as a branch that is merged locally: 1. `npm run create:branch -- /`. 2. Commit your work (one or more commits, per the tests and style rules above). 3. `npm run verify` — the definition of done. -4. `npm run create:finish` to merge the branch into `main` and verify the +4. Add a changelog note under `[Unreleased]` (see + [Rules the tools don't enforce](#rules-the-tools-dont-enforce)). +5. `npm run create:finish` to merge the branch into `main` and verify the result. -5. Present a handover for review. Once there are no further objections, the +6. Present a handover for review. Once there are no further objections, the maintainer pushes. When the project is promoted to GitHub, this step becomes a normal pull request diff --git a/development/workflow.md b/development/workflow.md index bb7e518..c18502a 100644 --- a/development/workflow.md +++ b/development/workflow.md @@ -49,6 +49,36 @@ plus hand-written `git`. merge and the next push. `create:branch` requires `main` to match its upstream and refuses until it is pushed; push `main` before starting the next branch. +## Changelog notes + +The rule is in +[CONTRIBUTING.md § Rules the tools don't enforce](../CONTRIBUTING.md#rules-the-tools-dont-enforce). + +#### Decision (2026-09) + +A merged branch carries its own summary under `[Unreleased]` in +[CHANGELOG.md](../CHANGELOG.md), added before `create:finish`; +`create:release` graduates it into the tagged section (see +[publishing.md](./publishing.md)). + +#### Why + +- `create:release` derives the bump heuristic from the `[Unreleased]` body, so + the notes must exist before release day. +- The contributor has fresh context; at release day the intent of a branch is + only its diff. +- Gitmoji subjects are signposts, not semantic keys, so notes cannot be derived + from the history. + +#### Rejected + +- Generating notes from subjects at release time: subjects carry no parseable + type/scope (see § Commit messages). +- The maintainer writing one summary during `create:release`: reconstruction + after the fact. +- Enforcing it in `create:finish`: the front doors assert git state, not + content — and _notable_ is exactly the judgment a tool cannot make. + ## Script prefix convention The prefix taxonomy is the rule, and it lives in