Release Notes skill for Codex

Release notes are done when a user can tell in ten seconds whether they must do anything before upgrading, can find the change that matters to them, and every entry describes what they will notice, not what the team did internally.

Release notes describe one version for its users. Keeping a cumulative CHANGELOG.md file is $changelog-writing; turning a release into a marketing post or email is $changelog-to-announcement.

Gather the changes

git describe --tags --abbrev=0                       # last tag
git log --oneline --no-merges v1.8.0..HEAD           # commits since then
gh pr list --state merged --base main --search "merged:>=2026-09-01" \
  --json number,title,labels,author,body --limit 200 # PRs with labels and bodies (network)
gh api repos/{owner}/{repo}/releases/generate-notes -f tag_name=v1.9.0 -f previous_tag_name=v1.8.0 \
  --jq .body                                          # GitHub's auto draft, as raw input only

Read AGENTS.md, CONTRIBUTING.md and previous releases (gh release view v1.8.0) for the house format, tone and section names. Match them unless the user asked for a change.

If the project uses Conventional Commits, types give a first sort (feat, fix, feat!/BREAKING CHANGE:), but commit subjects are written for developers; rewrite them.

Workflow

- [ ] 1. Determine the version range (last tag..release commit) and the audience
- [ ] 2. Collect PRs/commits with labels, bodies and linked issues
- [ ] 3. Drop internal-only changes (table below); keep a list of what was dropped
- [ ] 4. Classify the rest; find breaking changes, deprecations, security fixes first
- [ ] 5. Rewrite each kept entry as user impact
- [ ] 6. Write the summary line and required-action block
- [ ] 7. Verify every claim (flag names, defaults, versions) against the code
- [ ] 8. Create a DRAFT release; publish only after the user confirms

Keep or drop

Change	In release notes?
New feature, option, endpoint, command	Yes
Behaviour change, new default, removed option	Yes, under breaking or changed
Bug fix users could have hit	Yes, describe the symptom that is gone
Security fix	Yes, with CVE/GHSA ID and severity when public; follow the disclosure plan
Performance improvement with a measurable effect	Yes, with the number
Dependency bump that changes supported versions or fixes a CVE	Yes
Refactors, CI, tests, internal tooling, typo fixes in code comments	No
Dependency bumps with no user-visible effect	No (or one collapsed line)
Docs changes	Only if significant (new guide)

Structure

Order sections by how much they demand from the reader:

1. Summary: one or two sentences on what this release is about.
2. Action required / Breaking changes: what breaks, who is affected, exactly how to migrate, with before/after code.
3. Security: fixes and advisories.
4. New: features, with one sentence on why someone would use them and a docs link.
5. Changed / Improved: behaviour and performance changes.
6. Fixed: symptom-based bug fixes.
7. Deprecated: what will be removed, in which version, and the replacement.
8. Known issues: with workarounds.
9. Upgrade: the command, and contributors or full changelog link if the project credits them.

Omit empty sections.

Rewriting entries

PR title (input)	Release note (output)
fix: handle nil ptr in cfg loader	Fixed a crash on startup when config.yaml contains an empty storage: block.
feat(api): add cursor param	List endpoints now accept a cursor parameter for stable pagination over large result sets. See Pagination.
perf: batch inserts in sync	Initial sync of large workspaces is about 3x faster (12 min to 4 min for 50k records in our benchmark).
chore!: drop node 18	Breaking: Node.js 18 is no longer supported. Upgrade to Node.js 20 or later before installing 3.0.

Rules:

• Lead with the user-visible effect; mention the mechanism only if it helps them act.
• Name exact flags, settings, endpoints and versions in code formatting.
• Bugs: describe the symptom users saw (“exports silently skipped rows with emoji”), so people searching for their problem find it.
• Numbers instead of adjectives (“40% smaller bundle”, not “much smaller”).
• Credit external contributors by handle if that is the project’s convention.
• Never promise future features or dates unless the user supplies and approves them.

Breaking change block

## Action required

**`timeout` is now in seconds, not milliseconds.** Applies to everyone who sets `timeout`
in `client.config`. Values were silently 1000x too long before; requests that relied on
very long timeouts may now fail fast.

```diff
- client = Client(timeout=30000)
+ client = Client(timeout=30)
```

GitHub configuration for better auto drafts

.github/release.yml controls how GitHub groups auto-generated notes:

changelog:
  exclude:
    labels: [skip-changelog, internal, dependencies]
    authors: [dependabot, renovate]
  categories:
    - title: Breaking changes
      labels: [breaking-change]
    - title: New features
      labels: [feature, enhancement]
    - title: Bug fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

Auto-generated notes are a starting draft. The rewrite above is still needed.

Publishing

gh release create v1.9.0 --draft --title "v1.9.0" --notes-file release-notes.md --verify-tag
gh release view v1.9.0 --web           # let the user review the rendered draft

Creating a draft is safe. Publishing (gh release edit v1.9.0 --draft=false), pushing a tag, posting to an app store or announcing anywhere is outward-facing: do it only after the user has reviewed the draft and explicitly confirmed. Publishing a GitHub release can trigger deploy or package-publish workflows; check .github/workflows for on: release before suggesting it.

Channel formats

Channel	Format and limits
GitHub Release	Full Markdown, all sections above
Docs site release page	Same content; add anchors per version for linking
App Store “What’s New”	Plain text, up to 4,000 characters; 3-5 short bullet-style lines, most valuable first
Google Play “What’s new”	Plain text, 500 characters per language
In-product “What’s new”	One headline and one sentence per item, max 3 items, link to full notes

Gotchas

• Copying PR titles verbatim: developer jargon, no impact, no search value.
• Hiding a breaking change under “Changed”. If anyone must edit code or config to upgrade, it goes in “Action required”.
• Security fixes described in enough detail to exploit before users can patch. Follow the advisory timing; link the GHSA once published.
• Mentioning features that were merged but are behind a disabled flag in this release.
• Version numbers in notes that do not match the tag or package version.

Verification

• Every entry maps to a merged PR or commit in the range; every PR in the range is either in the notes or on the dropped list.
• Flag names, defaults and supported versions checked against code at the release commit.
• Breaking-change migration snippets run, or are marked as untested.
• Draft rendered and reviewed by the user before any publish step.

Report

**Range:** v1.8.0..v1.9.0 (47 PRs)
**In notes:** 18 (1 breaking, 1 security, 5 new, 4 changed, 7 fixed)
**Dropped as internal:** 29 (list attached)
**Draft:** created as GitHub draft release v1.9.0, not published
**Needs confirmation:** publish the draft; whether to name the reporter of GHSA-xxxx