Skip to content

Publish changelog entries as release notes - #34

Merged
trsdn merged 2 commits into
mainfrom
trsdn-changelog-release-gate
Aug 31, 2026
Merged

trsdn merged 2 commits into
mainfrom
trsdn-changelog-release-gate

Conversation

@trsdn

@trsdn trsdn commented Aug 31, 2026

Copy link
Copy Markdown
Owner

Problem

CHANGELOG.md had an empty ## Unreleased section and was completely disconnected from the release pipeline:

  • The publish job created the GitHub release with a fixed sentence ("Signed, notarized, stapled, and verified macOS release artifacts.") and never read the changelog.
  • Nothing failed when a tagged version had no changelog section, or when entries were still parked under ## Unreleased — those entries silently never reached any release notes.
  • bump-version.sh bumped the project and website version but left the changelog untouched, so drifting apart was the default outcome.

R06 of the Repository Quality Standard was recorded as pass on exactly this evidence, which shows how weak the criterion is when nothing consumes the changelog. A matching change to the standard is being prepared in trsdn/.github.

Change

The changelog is now the single source of the release body.

  • scripts/changelog.sh (new): section <version|unreleased> prints one section, release-notes <version> [--output FILE] verifies release readiness and emits the notes. It fails when the version has no dated section, when that section is empty, or when entries are still parked under ## Unreleased.
  • release.yml: the metadata job checks out the tooling, reads CHANGELOG.md from the tag itself, and gates the release before any test, build, or signing work happens. The published notes come from that section (gh release create/edit --notes-file).
  • bump-version.sh: promotes the ## Unreleased entries into the new dated ## X.Y.Z - YYYY-MM-DD section and refuses to bump when there is nothing to release. It keeps updating the project and site version markers.
  • check-documentation.sh: additionally verifies that the changelog keeps an ## Unreleased section and describes the current MARKETING_VERSION. The existing CI lint job already runs this script and bash -n scripts/*.sh.
  • AGENTS.md / README.md: document the convention; CLAUDE.md stays a pointer.
  • CHANGELOG.md: the user-facing work merged with Apply Repository Quality Standard v1.5.1 #33 is described as well, so the next release notes are complete.

Verification

  • bash -n scripts/*.sh, scripts/check-documentation.sh, and scripts/verify-version.sh pass.
  • Full bump flow exercised on the merged scripts: entries are promoted, project version, softwareVersion, both visible site markers, and the review date are updated, and the resulting tag passes the gate.
  • Failure paths verified: unknown version, empty section, malformed date heading, parked unreleased entries, and bumping with an empty ## Unreleased.
  • Gate replayed against every historical tag (v1.1.0v1.2.0), so workflow_dispatch re-runs of older tags still work; v1.0.0 predates the changelog entirely.

trsdn and others added 2 commits August 31, 2026 13:56
The release workflow created GitHub releases with a fixed boilerplate
sentence and never read CHANGELOG.md, so entries parked under
"## Unreleased" silently missed every release and nothing failed when a
tagged version had no changelog entries at all.

The changelog is now the single source of the release body. A new
scripts/changelog.sh extracts and verifies one section, the metadata job
gates the release on the tagged version having entries and on no entries
being left unreleased, and the publish job uses that section as the
release notes. bump-version.sh promotes the unreleased entries into the
dated section it creates, and CI verifies documentation, script syntax,
and changelog consistency on every run.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 193fe4f0-675a-4655-8754-3b20d216f398
Adapts the changelog gate to the Repository Quality Standard layout that
landed on main: the release and changelog rules move into AGENTS.md,
CLAUDE.md stays a pointer, the changelog checks join the existing
documentation checks that the CI lint job already runs, and
bump-version.sh keeps the site version markers while promoting the
unreleased entries.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 193fe4f0-675a-4655-8754-3b20d216f398
@trsdn
trsdn merged commit e8eacf4 into main Aug 31, 2026
8 checks passed
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