From 0a825c821e90bb76f20c059a519c840a9249377c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 14:51:22 +0000 Subject: [PATCH] Trim release notes to highlights when the changelog entry is huge The "Extract changelog section for this version" step used to hand the whole cut CHANGELOG.md section to the GitHub Release body verbatim, regardless of length -- fine for short entries, but this project's entries routinely run to several thousand characters across many "### " subsections (see v2.4.0), making for an unreadable release page. Sections at or under 1500 characters still work that way; past that, the body is reduced to the section's "### " subsection headings (or its top-level "- **bold**" bullets, for a version with no subsections) plus a link back to CHANGELOG.md for the full write-up. Same change applied to CoverDex's release.yml for consistency between the two pipelines. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01VQrE6ntdCMh5JQfS5m5WVL --- .github/workflows/release.yml | 40 +++++++++++++++++++++++++++++------ CHANGELOG.md | 20 ++++++++++++++++-- 2 files changed, 51 insertions(+), 9 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index aae14ac..b664a2a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,9 +8,15 @@ # form can't pre-fill a value computed from repo state) and is only # validated to be greater than the current VERSION_STRING. The CHANGELOG # heading is just "## vX.Y.Z (date)" — no separate title to type in; the -# Unreleased section's own content (used verbatim as the GitHub Release -# body too) already says what the release is about. The workflow refuses -# to overwrite an existing release/tag. +# Unreleased section's own content already says what the release is about. +# That content becomes the GitHub Release body verbatim only when it's +# short — past a size threshold (see "Extract changelog section for this +# version" below) the release body is trimmed down to just its "### " +# subsection headings (or top-level "- **bold**" bullets, for a version +# with no subsections) plus a link back to CHANGELOG.md, since a huge +# release body is unreadable on the GitHub Releases page and the full +# write-up is already versioned in the repo. The workflow refuses to +# overwrite an existing release/tag. name: Release on: @@ -144,9 +150,13 @@ jobs: - name: Build run: make - # Release notes come straight from CHANGELOG.md: the section for the - # version just cut above (from its "## vX.Y.Z ..." heading up to the - # next one). + # Release notes come from CHANGELOG.md: the section for the version + # just cut above (from its "## vX.Y.Z ..." heading up to the next + # one), used verbatim when short. Past 1500 characters that full + # text is unwieldy as a release body, so only the "### " subsection + # headings (or top-level "- **bold**" bullets, for a version with no + # subsections) are kept, followed by a link back to CHANGELOG.md for + # the rest. - name: Extract changelog section for this version id: changelog env: @@ -162,7 +172,23 @@ jobs: echo "::error::No CHANGELOG.md section found for ${RELEASE_TAG} right after cutting it — this should not happen." exit 1 fi - printf '%s\n' "$BODY" > /tmp/release_notes.md + + CHANGELOG_URL="https://github.com/${GITHUB_REPOSITORY}/blob/main/CHANGELOG.md" + BODY_SIZE=$(printf '%s' "$BODY" | wc -c) + + if [ "$BODY_SIZE" -le 1500 ]; then + printf '%s\n' "$BODY" > /tmp/release_notes.md + else + HIGHLIGHTS=$(printf '%s\n' "$BODY" | grep -E '^(### |- \*\*)' | sed -E 's/^### (.*)$/- \1/') + if [ -z "$HIGHLIGHTS" ]; then + HIGHLIGHTS=$(printf '%s\n' "$BODY" | awk 'BEGIN{p=0} /^[[:space:]]*$/{if(p)exit; next} {print; p=1}') + fi + { + printf '%s\n\n' "$HIGHLIGHTS" + printf 'See [CHANGELOG.md](%s) for the full write-up.\n' "$CHANGELOG_URL" + } > /tmp/release_notes.md + fi + echo "notes_file=/tmp/release_notes.md" >> "$GITHUB_OUTPUT" - name: Create GitHub Release diff --git a/CHANGELOG.md b/CHANGELOG.md index 61d1b89..0083d09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,9 @@ release is a manual, deliberate step: trigger the `Release` GitHub Actions workflow (`.github/workflows/release.yml`) with just a version number — it renames this file's `## Unreleased` section to `## vX.Y.Z (date)`, bumps `VERSION_STRING` to match, builds, and publishes the result as a -GitHub Release using that section verbatim as the release notes. Keep -the `## vX.Y.Z` heading format exact. +GitHub Release using that section as the release notes — verbatim when +it's short, or trimmed to just its `### ` headings plus a link back here +when it's long. Keep the `## vX.Y.Z` heading format exact. **Policy:** every change gets a `CHANGELOG.md` entry under a `## Unreleased` section at the top of this file when it's made (create the section if it @@ -16,6 +17,21 @@ accurate at all times instead of being reconstructed from memory later. ## Unreleased +### Changed: release notes now trim to highlights when the changelog section is huge +`.github/workflows/release.yml`'s "Extract changelog section for this +version" step used to hand the entire cut `## vX.Y.Z` section to +`softprops/action-gh-release` verbatim, no matter its length — fine for a +short entry, but this project's changelog entries routinely run to +several thousand characters across many `### ` subsections (see `v2.4.0` +below), which makes for an unreadable wall of text on the GitHub Releases +page. Now: sections at or under 1500 characters are still used verbatim, +unchanged. Past that, the release body is reduced to just the section's +`### ` subsection headings (or its top-level `- **bold**` bullets, for a +version written without subsections) as a bullet list, followed by a +link back to `CHANGELOG.md` for the full write-up. Same change applied +to CoverDex's `release.yml` for consistency between the two projects' +pipelines. + ## v2.4.0 (2026-08-19) ### Fix: release workflow failing on every run, unrelated to the PAT