| name | release-highlights |
| description | Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics. |
Release highlights
Every tag's release body is auto-generated by .github/workflows/release.yml: NEW_NOTES (GitHub's generate-notes → ## What's Changed + Full Changelog) followed by the ## Downloads table (.github/templates/release-notes-downloads.md). Highlights are not part of that flow. A ## Highlights section is written by hand after the release exists and prepended to the auto-generated body — leave ## What's Changed and ## Downloads untouched. Precedent: v1.9.0 (TUI), v1.9.1 (npm + cloud shell), v1.9.2 (CloudShell fix).
When a release earns highlights
Write them when a reader skimming the release needs a "what changed and why it matters" that the raw PR list doesn't convey:
- A headline feature or epic (v1.9.0 TUI, v1.9.1 npm distribution).
- A distribution / install change users act on.
- A notable fix, especially one that supersedes an earlier release's approach (v1.9.2 CloudShell — say so and reference the prior version).
A pure dependency-bump or internal-only patch does not need them.
Format (match it exactly)
## Highlights heading.- A bold one-sentence lead naming the release and its theme, followed by a breaking-change statement — almost always
No breaking changes; existing CLI, TUI, and GUI behavior is unchanged. Only claim a break when there genuinely is one.
### subsections grouping related items (e.g. Distribution, Cloud shell support, TUI, Documentation, Quality, CI). Order most-to-least user-facing.- Bulleted items, each a bolded phrase then an em-dash explanation, ending with
(#PR) references. Cite the PRs that delivered the item; a coverage/sweep item may cite a range (#831–#848).
Keep it accurate: only claim what the PRs actually did, and don't assert an epic is "complete" unless verified.
Mechanics
Reconstruct the full body (Highlights + existing) rather than editing in the GitHub UI — the auto-generated tail must survive verbatim.
gh release view vX.Y.Z --json body -q .body > body.md
cat highlights.md body.md > full.md
gh release edit vX.Y.Z --notes-file full.md
immutable: true on a release refers to its assets, not the body — the notes stay editable, and re-running gh release edit is safe and reversible.
Editing a public release page is outward-facing; draft the Highlights text and confirm with the maintainer before publishing unless already told to proceed.
