Skip to content

ci(release): create the GitHub release from the CHANGELOG section - #48

Open
jameslcowan wants to merge 2 commits into
mainfrom
ci/release-notes
Open

jameslcowan wants to merge 2 commits into
mainfrom
ci/release-notes

Conversation

@jameslcowan

Copy link
Copy Markdown
Collaborator

What changed

release.yml published to npm and left the GitHub release to a manual step in CONTRIBUTING.md. The step was skipped 9 times: until today the newest GitHub release was 0.4.1 while npm had 0.11.0. A visitor to the repository saw a project 7 published versions behind its package.

The 9 missing releases now exist, made by hand from the same CHANGELOG sections this workflow will read (v0.5.0 to v0.11.0, v0.11.0 marked latest). This pull request makes the next ones automatic.

  • A github-release job runs after publish succeeds. It creates the release for the tag, or edits it on a re-run, with the title complex-md X.Y.Z.
  • The notes are the version's CHANGELOG.md section. scripts/release-notes.mjs reads it from ## YYYY-MM-DD X.Y.Z: summary to the next ## heading and joins the wrapped lines of each paragraph, because a release page shows every line break.
  • The publish job checks that the section exists before npm ci, so a release with no notes stops before anything is published.
  • Permissions: the workflow default is contents: read. publish keeps id-token: write with read access. Only github-release gets contents: write. All actions stay pinned to commit SHAs (checkout 7.0.1, setup-node 7.1.0, as in the other workflows).
  • CONTRIBUTING.md states the heading format and that the workflow creates the release.

What it does not do: a tag whose version has no X.Y.Z: heading fails the release before publish. 2 old versions, 0.5.0 and 0.7.0, had sections with no version in the heading; their releases were made by hand.

How it was tested

  • cli/test/release-notes.test.js: the reader on a fixture (a section ends at the next heading, 0.9.1 never takes the 0.9.10 section, CRLF reads the same, a leading v is accepted), and the real CHANGELOG.md has a section for the version in cli/package.json.
  • node scripts/release-notes.mjs produced the notes of the 7 versioned releases created today; 99.0.0 exits 1 with the expected heading in the message.
  • cd cli && npm test: exit 0, 844 pass, 0 fail, 2 todo.
  • The workflow parses; job permissions are publish: {contents: read, id-token: write} and github-release: {contents: write}.
  • Not testable before a tag: the gh release create call itself. The first real run is the next release; if it fails, the npm publish has already succeeded and a re-run of the github-release job alone is safe.

AI assistance

  • An AI tool helped write this change. Claude Code (Claude Opus 5.5) wrote the script, the workflow change, the commits and this description.
  • Each commit the tool helped write has an Assisted-by: or a Co-Authored-By: trailer.
  • A person read the whole diff and will answer the review comments.
  • Or: a maintainer agent opened this pull request, and "Maintainer agents" in CONTRIBUTING.md decides who merges it (gated: the owner label).

🤖 Generated with Claude Code

https://claude.ai/code/session_011jHASLngEodgNzogro3gQz

Problem: release.yml published to npm and left the GitHub release to a
manual step that CONTRIBUTING.md described. The step was skipped 9 times:
the newest GitHub release was 0.4.1 while npm had 0.11.0, and a visitor
to the repository saw a project 7 releases behind its package.

Change: a github-release job runs after the publish job and creates the
release for the tag, or edits it on a re-run. Its notes are the version's
CHANGELOG.md section, which scripts/release-notes.mjs reads from the
heading `## YYYY-MM-DD  X.Y.Z: summary` to the next heading, with the
wrapped lines of each paragraph joined. The publish job checks that the
section exists before it publishes anything. Permissions: the workflow
default is contents: read; the publish job keeps id-token: write; only
the new job gets contents: write. cli/test/release-notes.test.js covers
the reader and fails when cli/package.json names a version with no
section. CONTRIBUTING.md states the heading format.

Intent: every published version has a GitHub release with real notes,
with no manual step to forget.

Assisted-by: Claude
# Conflicts:
#	.github/workflows/release.yml
#	CHANGELOG.md
@jameslcowan jameslcowan added the owner Gated: the maintainer reviews and merges label Nov 12, 2026
@jameslcowan

Copy link
Copy Markdown
Collaborator Author

Left open for the maintainer. CI is green on all 7 jobs (the comment job failed once with "complex-md-action: fetch failed", a network error, and passed on re-run). This pull request changes release.yml, so it is gated under "Maintainer agents" and carries the owner label. The GitHub releases for the 9 existing tags are already created, so nothing waits on this merge until the next tag.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

owner Gated: the maintainer reviews and merges

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant