Skip to content

fix(boxel-cli): narrow release notes; restrict CHANGELOG to stable cuts#4880

Merged
FadhlanR merged 2 commits into
mainfrom
fix-boxel-cli-changelog-path-filter
May 19, 2026
Merged

fix(boxel-cli): narrow release notes; restrict CHANGELOG to stable cuts#4880
FadhlanR merged 2 commits into
mainfrom
fix-boxel-cli-changelog-path-filter

Conversation

@FadhlanR
Copy link
Copy Markdown
Contributor

@FadhlanR FadhlanR commented May 19, 2026

Summary

Two fixes to the boxel-cli publish flow's release-notes story, building on the OIDC/annotated-tag fix in #4879.

1. Filter release notes to commits that touched packages/boxel-cli/

The ## Changes block in every boxel-cli GitHub Release body and CHANGELOG.md entry was listing every PR merged repo-wide between two boxel-cli-v* tags — 50+ bullets per release, mostly unrelated observability / host / realm-server work. Root cause: generate-release-notes.ts sourced its bullets from gh api releases/generate-notes, which filters by merge date with no paths: filter.

Replaced with a local builder that:

  • git log <prev>..HEAD --pretty='%H%x09%an%x09%s' -- packages/boxel-cli/ — filters to commits that actually touched the package.
  • Drops github-actions[bot] rows (the chore(release): … commits the workflow pushes itself).
  • Resolves each remaining SHA to its PR via gh api commits/<sha>/pulls and emits * <title> by @<user> in <PR URL> (same shape GitHub's auto-notes use).
  • Dedupes by PR number.
  • Keeps the **Full Changelog**: <compare URL> footer.

2. Restrict CHANGELOG.md to stable cuts

Per-merge unstable bumps were writing entries to packages/boxel-cli/CHANGELOG.md, which isn't what a changelog is for. Now:

  • The unstable job no longer prepends to CHANGELOG.md and no longer stages it in the bot commit. It still produces a rich filtered Release body, posted to GitHub Releases.
  • The stable job still writes CHANGELOG.md (one entry per stable promotion, aggregating PRs since the previous stable).
  • The file is reset to its seed state — the three existing entries (.293 / .294 / .298) were all generated with PREV_TAG=boxel-cli-v0.1.4 (because the lightweight-tag bug fixed in fix(boxel-cli): consolidate publish workflows, push annotated tags #4879 left intermediate tags unpushed, so git describe kept walking back), so they were all the same noisy ~50-PR repo-wide list and not worth keeping.

Out of scope

The compute-release.ts stable-tag logic stays as-is. A defense-in-depth boundary fix (using the previous bot commit instead of the previous tag) is no longer necessary now that CHANGELOG.md is stable-only; a noisy Release body in the edge case of a future tag-push failure is much lower-impact than a noisy on-disk changelog.

Test plan

  • pnpm --filter @cardstack/boxel-cli exec vitest run tests/scripts/generate-release-notes.test.ts — 15 tests pass (9 existing + 6 new for buildFilteredNotes).
  • pnpm --filter @cardstack/boxel-cli lint — eslint + tsc clean.
  • pnpm --filter @cardstack/boxel-cli test:unit-exclude-smoke — full unit suite (231 tests) green.
  • yamllint -c .github/.yamllint.yml .github/workflows/boxel-cli-publish.yml — clean.
  • Local dry-run of the filter against boxel-cli-v0.1.4..HEAD — produced 5 boxel-cli-only bullets (vs 50+ pre-fix). All @FadhlanR, no bot commits, proper PR URLs and Full Changelog footer.
  • After merge — next feat(boxel-cli): PR's auto-publish: the bot commit on main does NOT touch CHANGELOG.md, and the GitHub Release body lists only boxel-cli PRs.
  • After merge — first workflow_dispatch stable promotion: writes the first real entry to CHANGELOG.md.

🤖 Generated with Claude Code

FadhlanR and others added 2 commits May 19, 2026 13:15
The `## Changes` block in `CHANGELOG.md` and the GitHub Release body was
listing every PR merged repo-wide between two `boxel-cli-v*` tags — 50+
bullets for unrelated observability, host, and realm-server work on every
boxel-cli publish. Root cause: `generate-release-notes.ts` sourced its
body from `gh api releases/generate-notes`, which filters by merge date,
not by `paths:`.

Replace that with a local builder that:
- `git log <prev>..HEAD --pretty='%H%x09%an%x09%s' -- packages/boxel-cli/`
  to filter to commits that actually touched the package,
- drops `github-actions[bot]` rows (the `chore(release): …` bumps the
  workflow pushes itself),
- resolves each remaining SHA to its PR via `gh api commits/<sha>/pulls`
  and emits a `* <title> by @<user> in <PR URL>` bullet,
- dedupes by PR number,
- keeps the `**Full Changelog**: <compare URL>` footer.

Pin `git log`'s cwd to the repo root — the workflow invokes the script
from `packages/boxel-cli/`, where the relative path filter would
otherwise resolve to a non-existent nested directory.

Outer `composeReleaseBody` / `composeChangelogFragment` unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Only the stable promotion job writes `packages/boxel-cli/CHANGELOG.md`
now. The per-merge unstable job still produces a rich filtered GitHub
Release body but doesn't append to the on-disk changelog. Per-bump
unstable detail stays available on the Releases page and on npm.

Reset `CHANGELOG.md` to its seed state so the file starts fresh on the
next stable cut — the existing `.293` / `.294` / `.298` entries were
all generated with `PREV_TAG=boxel-cli-v0.1.4` (the lightweight-tag
bug fixed in #4879 left intermediate tags unpushed, so `git describe`
kept walking back to the last actually-pushed tag). Each entry was
the same noisy ~50-PR repo-wide list and not worth keeping around.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@FadhlanR FadhlanR changed the title fix(boxel-cli): filter release notes to commits that touched the package fix(boxel-cli): narrow release notes; restrict CHANGELOG to stable cuts May 19, 2026
@FadhlanR FadhlanR marked this pull request as ready for review May 19, 2026 06:40
@FadhlanR FadhlanR merged commit b417396 into main May 19, 2026
28 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