Release Highlights

Release Highlights

Adds a # Highlights section between the badge row and ## What's Changed on a published release. Nothing else about the release changes.

The invariant

Everything from ## What's Changed down is generated once, at publish time, and cannot be rebuilt. It carries the compare link, the New Contributors block, the build provenance attestation ID, and the CI run URL. Those come from the publish-time workflow run. If they are overwritten they are gone.

So: never regenerate a release body. Never call gh release edit --notes with prose you composed. Never let gh release create --generate-notes near an existing release. The only supported write is scripts/insert_highlights.py, which fetches the live body, splits it at the marker, and reassembles it with the tail byte-identical — then re-fetches and proves the tail did not change, printing a restore command if it did.

If the script refuses, that refusal is the feature. Do not work around it by editing the body by hand.

Steps

1. Resolve the target

• No argument → the newest release: gh release list --repo garfiec/Librechat-Mobile --limit 1
• Explicit tags → exactly those, in the order given.
• --backfill → every release with no Highlights section. Enumerate them and confirm before touching any. There are releases going back to v0.1.1 that predate both calver and the Switchboard rename; they are almost never what the user meant. --since <tag> sets a floor. Backfill never runs implicitly.

Refuse a tag that already has a Highlights section. Replacing one is a separate, explicit request, and only then does --replace get passed.

2. Read the release and every PR in it

gh release view "$TAG" --repo garfiec/Librechat-Mobile --json body -q .body

Extract the PR numbers from the What's Changed list, then read every one of them:

for p in $PRS; do
  echo "=== #$p"
  gh pr view "$p" --json title,body -q '.title + "\n" + (.body | .[0:800])'
done

Read all of them, including the ones that look mechanical — a chore( prefix sometimes hides a user-visible change, and a feat( prefix sometimes hides pure plumbing. The title is a claim about the change, not a description of its effect; the body's Summary/Problem section is what tells you whether a user would notice.

For each PR decide one thing: what changes for someone using the app? If the answer is "nothing they could observe", it is not a Highlights bullet.

3. Ask about anything ambiguous — once, before drafting

Collect every uncertain item across the whole release and ask them in a single round. Do not draft first and ask afterwards, and do not interrupt per-PR.

What counts as ambiguous is not "I don't understand the change" — read the PR again for that. It is when the change is understood but its framing is a judgment call the user owns:

• Was this broken in a shipped build, or never working at all? ("banners display again" vs. "banners display" — the first claims a regression that may never have existed)
• Is a fix worth naming, or is it noise that belongs in the Misc lines?
• Does a staged feature land in this release or the next one?
• Is an internal-sounding change actually user-visible?

If nothing is ambiguous, ask nothing.

4. Draft in the house style

# Highlights

* Features
  * <short user-facing phrase>
* Bug Fixes
  * <short user-facing phrase>
* Performance Improvements
* Misc Tech Debt Refactors
* Misc Stability Improvements

Rules, in force regardless of what prior releases happen to look like:

• Categories are fixed and ordered: Features, Bug Fixes, Performance Improvements, Misc Tech Debt Refactors, Misc Stability Improvements. Omit any with nothing to say — a release with no features has no Features line. A new top-level category is allowed when a release genuinely does not fit, but say so explicitly when presenting the draft.
• A category with nothing nameable stays a bare bullet. * Performance Improvements with no children is correct and common; it signals the work happened without itemizing it.
• Sub-bullets are user-facing effects, in the user's vocabulary, sentence case, no trailing period, no PR links, no PR numbers, no commit-message prefixes. "Two-factor authentication now works end to end", not "fix(auth): make 2FA login work end to end".
• Collapse staged PRs into one bullet. A feature delivered across several PRs is one thing to a user. Five prefetch PRs (#335, #341, #342, #343, #344) are one line about background cache warming; three access-gateway PRs (#294, #298, #312) are one line about custom request headers.
• Never name infrastructure work individually. Dependabot bumps, CI changes, test additions, Claude skills, dead-code removal, comment cleanups, docs — these fold into the two Misc lines and are never their own sub-bullet.
• Lead with the most visible change. If the release renames the app or changes the launcher icon, that is the first bullet.
• Keep it to roughly 3–6 sub-bullets per category. If Bug Fixes runs to ten, the tail of the list is Misc Stability Improvements.