Skip to content

ci: take the release page's prose from the CHANGELOG too - #391

Open
gloryfromca wants to merge 1 commit into
mainfrom
ci/release-notes-from-changelog
Open

ci: take the release page's prose from the CHANGELOG too#391
gloryfromca wants to merge 1 commit into
mainfrom
ci/release-notes-from-changelog

Conversation

@gloryfromca

Copy link
Copy Markdown
Collaborator

Summary

Follow-up to #389. That PR left two things to be written at publish time — the lead summary and the upgrade notes — which is the worst moment for it: the changes are weeks old by then and the text gets no review. Both belong in the CHANGELOG entry the release PR is already editing.

  • The lead needed no code. Text between ## [X.Y.Z] and the first ### group already flowed into the page; it was just never documented, so nobody wrote it there.
  • The Upgrade group did. CI appended its own ## Upgrade, so a CHANGELOG carrying upgrade notes produced two headings. The group is now lifted out of the extracted body and the boilerplate wrapped around it — pip line above, prose in the middle, compare link below — which is the shape of every release page since 1.1.3.

Publishing becomes a read-through and a click.

Area

  • CI, build, or release

Verification

Extraction re-run from the workflow YAML against a fixture repo (CHANGELOG with a lead paragraph and an ### Upgrade group, tags v1.2.2 / v1.3.0) and against the real CHANGELOG.md:

fixture v1.3.0  rc=0
  lead paragraph, verbatim, above the first heading
  ## Added / ## Fixed
  ## Upgrade -> pip block, then the CHANGELOG's upgrade prose, then
                **Full changelog:** [v1.2.2...v1.3.0](...)
  one "## Upgrade" heading, not two

fixture v1.2.2  rc=0   no lead, no Upgrade group -> pip block only
real    v1.2.2  rc=0   ## Added / ## Changed / ## Fixed / ## Docs / ## Upgrade
                       one "## Upgrade" heading

Output for the fixture matches the hand-written v1.2.1 page section for section.

Checklist

  • I kept the change scoped to the relevant area.
  • I am opening this from a separate branch, not pushing directly to main.
  • I updated docs, examples, or setup notes when behavior changed.
  • I added or updated tests when the change affects behavior.
  • I did not commit secrets, .env files, dependency folders, or generated output.
  • Active relative links in Markdown files resolve.

Notes for Reviewers

The /release skill now shows the CHANGELOG entry as the source of the page and says to omit the ### Upgrade group when there is nothing to say — 1.1.4 and 1.2.0 have nothing there, and prompting for filler is how a section becomes noise.

Still unverified end to end: the job has never run on a real tag push. Same open question as #389 — an rc tag would settle it.

🤖 Generated with Claude Code

Leaving the lead summary and the upgrade notes to be composed at publish
time put the writing at the worst possible moment — weeks after the changes,
with no review. Both belong in the CHANGELOG entry, which the release PR is
already editing.

The lead needed no code: text between the version heading and the first
group already flowed into the page. The Upgrade group did — CI appended its
own `## Upgrade`, so a CHANGELOG that carried upgrade notes produced two
headings. The group is now lifted out and the boilerplate wrapped around it,
pip line above, compare link below, matching every page since 1.1.3.

Publishing is now a read-through and a click.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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