Skip to content

fix(changelog): restore [Unreleased] heading on main + document the rule#103

Merged
ThomasK33 merged 1 commit into
mainfrom
fix-changelog-unreleased-section
May 13, 2026
Merged

fix(changelog): restore [Unreleased] heading on main + document the rule#103
ThomasK33 merged 1 commit into
mainfrom
fix-changelog-unreleased-section

Conversation

@ThomasK33
Copy link
Copy Markdown
Member

@ThomasK33 ThomasK33 commented May 13, 2026

Summary

After the v0.2.0 release-prep commit (#102), ## [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:

× CHANGELOG.md exists but does not contain ## [Unreleased] or ## Unreleased; add an Unreleased section before running `communique generate HEAD --changelog`.

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-13 so 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.mjs could 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

  • `npm run format:check` clean
  • CI on this PR
  • After merge: confirm next push to main no longer fails the `Update Unreleased Changelog` workflow

🤖 Generated with Claude Code

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>
@ThomasK33 ThomasK33 merged commit 0624b8f into main May 13, 2026
12 checks passed
@ThomasK33 ThomasK33 deleted the fix-changelog-unreleased-section branch May 13, 2026 11:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant