fix(changelog): restore [Unreleased] heading on main + document the rule#103
Merged
Conversation
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 <tk@coder.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
After the v0.2.0 release-prep commit (#102),
## [Unreleased]was renamed to## [v0.2.0] - 2026-05-13but a fresh empty## [Unreleased]heading was not inserted above it. That leftmainwith no Unreleased section, which breaks theUpdate Unreleased Changelogworkflow that runs on every push to main:Failing run: https://github.com/coder/agent-tty/actions/runs/25795451618/job/75771464557
Changes
CHANGELOG.md— insert an empty## [Unreleased]heading above## [v0.2.0] - 2026-05-13so future post-release merges flow through the unreleased-changelog bot correctly.docs/RELEASE-PROCESS.md— new "`[Unreleased]` heading must stay on `main`" subsection. Spells out the rename-and-insert rule, explains that two separate workflows depend on the two different headings, shows the expected CHANGELOG.md shape after the release-prep commit, and instructs the maintainer to hand-edit CHANGELOG.md and amend before pushing the release-prep PR.Why I didn't catch this during the v0.2.0 cut
Both workflows that depend on the CHANGELOG headings are well-designed but their requirements pull in opposite directions:
Release Changelog(release-changelog.yml) keys off## [v<version>]to skip its Communique pass on the release branch — this is why I deliberately renamed## [Unreleased]→## [v0.2.0]in the release-prep commit.Update Unreleased Changelog(update-unreleased-changelog.yml) keys off## [Unreleased]to know where to insert post-merge entries on main.The correct shape carries both headings at once on main, with
[Unreleased]empty and[v<version>]carrying the finalized release notes. Doing the rename without inserting a fresh[Unreleased]satisfies the first workflow but breaks the second.Future improvement (not in this PR)
scripts/release-prep.mjscould be taught to perform the rename + fresh-Unreleased-insert automatically when invoked with `--changelog ci`, removing the manual editing step entirely. Tracked as a follow-up.Test plan
🤖 Generated with Claude Code