| name | release-notes |
| description | Write per-version release notes for nocturnal in the style established by `release-notes/0.9.1.md`. Use when cutting a new release, drafting notes for a tagged commit range, or revising existing notes to match the house format. |
Release notes style
Per-version notes live at release-notes/{version}.md in the repo root.
They are served at {RELEASE_URL}/release-notes/{version}.md so the agent
can fetch them on demand when the user asks "what's new?".
Format
Top-line header with the version and the release date:
# 0.9.1 — 2026-07-11
Section headings, in this order if they apply. Skip any section that has
nothing to put under it rather than emitting it empty.
- Breaking Changes — user-visible behavior changes that may require
action. Reserved for removals, keybinding changes, removed config keys.
- Features — new user-facing capabilities.
- Changes — default-value changes and other behavior shifts that are
neither pure bugfixes nor new features.
- Improvements — UX polish: faster, smoother, prettier, less noise.
- Bug Fixes — things that were broken and now work.
- Performance — measurable latency / throughput wins. Skip if a fix
is in Bug Fixes even if it was a perf-driven rewrite.
- Notes — security tightenings, deprecations, migration steps,
default-value caveats. Always include when defaults change.
Bullets are sentences. No implementation details, no commit hashes, no
file paths, no internal mechanism descriptions. The audience is the user,
not a maintainer.
Bold the user-visible noun on the first phrase of the bullet so a
scanner sees the topic, not the sentence. Example shapes:
- First-run setup wizard in the TUI and desktop guides you through...
- The model catalog now propagates from the server to all connected
clients without a manual refresh.
- OAuth providers (
openai-codex, xai-supergrok) no longer appear
in the model picker until a token is configured.
Inline code for config keys, file names, command names, key chords, CLI
flags. Backticks only, never bold.
Keep Notes paragraphs short. The Notes section is the only place where
a default-value warning or migration instruction is acceptable — these
are the bullets the user actually has to read.
Process when cutting a release
- Find the commit range:
git log v<prev>..HEAD --oneline (or the
previous tag, whichever is the most recent shipped version).
- Read each commit message body for context, but write for the user.
Drop anything that reads as engineering narration ("extracted to
server/model_catalog.rs", "serde(flatten) keeps wire format unchanged")
unless it directly describes a user-visible behavior change.
- Categorize. If a fix touches both provider behavior and UI, pick
the section the user will look for it under.
- Draft, then re-read with the question: would a user who never reads
the codebase understand every bullet?
- Drop the file into
release-notes/{version}.md and let
scripts/pkg-release.sh pick it up on the next release build.
