From 71212af0bba586f9f5ab12cca0d553589f65c70c Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Wed, 13 May 2026 13:19:58 +0200 Subject: [PATCH] fix(changelog): restore [Unreleased] heading on main + document the rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After the v0.2.0 release-prep commit, `## [Unreleased]` was renamed to `## [v0.2.0] - 2026-05-13` but a fresh empty `## [Unreleased]` heading was not inserted above it. That left `main` with no Unreleased section, which breaks the `Update Unreleased Changelog` workflow that runs on every push to main: `communique generate HEAD --changelog` errors with × CHANGELOG.md exists but does not contain ## [Unreleased] or ## Unreleased; add an Unreleased section before running `communique generate HEAD --changelog`. This change: - Restores an empty `## [Unreleased]` heading above `## [v0.2.0]` in CHANGELOG.md so future post-release merges flow through the unreleased-changelog bot correctly. - Adds a new "`[Unreleased]` heading must stay on `main`" subsection to docs/RELEASE-PROCESS.md spelling out the rename-and-insert rule, noting which workflows depend on which heading, and showing the expected CHANGELOG.md shape after the release-prep commit. The next maintainer who runs `release:prep --changelog ci` should hand-edit CHANGELOG.md and amend before pushing. A future enhancement could make `release:prep` perform the rename- and-insert automatically, but that's out of scope for this fix. Change-Id: Ib0cf1999efcd7180b723960098a92e2c500463f5 Signed-off-by: Thomas Kosiewski --- CHANGELOG.md | 2 ++ docs/RELEASE-PROCESS.md | 25 +++++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27387af..456f751 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog +## [Unreleased] + ## [v0.2.0] - 2026-05-13 ### Added diff --git a/docs/RELEASE-PROCESS.md b/docs/RELEASE-PROCESS.md index 2908176..07c48da 100644 --- a/docs/RELEASE-PROCESS.md +++ b/docs/RELEASE-PROCESS.md @@ -172,6 +172,31 @@ communique generate "v" --changelog --repo coder/agent-tty and commits the resulting `CHANGELOG.md` update back to the release branch. When it pushes that bot commit, it dispatches the CI and skill-validation workflows for the updated release branch so protected-branch checks can run against the new head commit. +### `[Unreleased]` heading must stay on `main` + +When preparing the release PR, **rename** the existing `## [Unreleased]` heading to `## [v] - ` and **insert a fresh empty `## [Unreleased]` heading immediately above it** before pushing. Do not remove `[Unreleased]` outright. + +Two workflows depend on this: + +- `Release Changelog` (release-changelog.yml) keys off `## [v]` to decide whether to run Communique on the release branch. Having `## [v] - ` present makes the workflow skip its Communique pass and preserve the curated `[Unreleased]` content that you just renamed. +- `Update Unreleased Changelog` (update-unreleased-changelog.yml) runs on every push to `main` and calls `communique generate HEAD --changelog`, which requires `## [Unreleased]` or `## Unreleased` to exist. If the heading is missing on `main`, every post-release merge fails this workflow until the heading is restored. + +So the right CHANGELOG.md state after the release-prep commit is roughly: + +```markdown +# Changelog + +## [Unreleased] + +## [v] - + +### Added + +... +``` + +`release:prep --changelog ci` does not edit `CHANGELOG.md` for you, so this rename + insert must be done manually (or via `release:prep --changelog local`, which lets Communique handle both steps). After running `release:prep --changelog ci`, edit `CHANGELOG.md`, then `git add CHANGELOG.md && git commit --amend --no-edit` to fold the change into the same release-prep commit. + ### Manual prep fallback If the scripted prep path is blocked, use the manual fallback only from a clean, up-to-date `main` checkout. Stage `package-lock.json` only if your checkout still has one (post-PR #91 the repo is aube-only and the file is absent):