release-notes

name	release-notes
description	Use to generate release notes for the next airlock release. Writes a single-file markdown summary aimed at end users.

Release notes

Writes release notes for the next airlock release to dev/tmp/release-notes.md.

Fetching the change set

Always scope to "commits since the last tagged release":

git log --oneline --reverse "$(git describe --tags --abbrev=0)..HEAD"

Use that list to decide the commits' user-facing impact. Inspect individual commits (git show --stat <sha>, git log -p <sha>) only when the one-line subject is ambiguous.

Record the previous tag name so the notes can reference it:

git describe --tags --abbrev=0

Abstraction level

The audience is end users, not contributors. Write at the level someone who runs airlock start would understand. That means:

• No symbol names, struct names, file paths, crate names, or function signatures. Never reference source modules.
• No signal names (SIGSEGV, SIGABRT), environment variables, or feature-flag names.
• No CLI flag names unless the flag itself changed. Existing flag names should be spelled out only when they help the user remember which feature you're talking about.
• No implementation detail words like "refactor", "wrap", "struct", "callback", "trait", "RPC", "mpsc", "atomic".

Use concrete, observable outcomes. "Log survives restarts" — not "append-mode file handle with rotation". "Pressing q closes the details pane" — not "hierarchical Esc handler". Binding-level keyboard shortcuts (q, F2) and in-UI labels (monitor tab, sandbox view) are part of the user's world; keep those.

Style

• Plain heading, then one unordered list.
• Each bullet starts with a bolded short phrase stating the change, followed by one short sentence of explanation. A second sentence is only allowed when it carries genuinely new information (a migration step, a non-obvious caveat). It is not for restating the bold phrase, hedging, or padding with "you can now..." style filler.
• Default is "one bullet ≈ one tweet." If you find yourself writing "in other words", "this means", or a parenthetical that re-says the same thing, cut it.
• Each bullet must be one unbroken line in markdown source. No mid-bullet hard line breaks. Most markdown renderers reflow anyway, and keeping it on one line makes the file easy to scan and edit.
• Keep the total under ~10 bullets. If the commit list is longer, group related commits under one bullet or drop pure-internal ones.
• Omit commits that have no user-visible effect: internal refactors, lint fixes, doc-only changes, test-only changes, dev-container tweaks. When in doubt, leave it out.

Output location

Write to dev/tmp/release-notes.md.

Template

# Release notes

Changes since `<previous tag>`:

- **<short bolded phrase>.** <one or two sentences of plain-language explanation on a single line>
- **<short bolded phrase>.** <one or two sentences of plain-language explanation on a single line>
- ...

Worked examples

Good (one sentence — that's enough):

Sparse disk shrinks live. The project disk image now reclaims deleted blocks back to the host every 10 minutes instead of staying at its high-water mark.

Good (two-sentence migration note — second sentence is new info, not a restatement):

User-level airlock.toml moves to ~/.airlock/. The user-level slot is now ~/.airlock/config.<ext> (was ~/.cache/airlock/config.<ext>). Move existing files before the next start.

Good (concrete symptom in plain language):

[env].HOME now drives container-side ~ expansion. Setting [env].HOME used to make $HOME and ~ disagree — they agree now.

Bad (padded — second half restates the first):

More robust macOS VM backend. Closes off the two most-likely paths for the rare "sandbox disappeared with a broken terminal" failure: any framework error is now caught cleanly instead of aborting the process, and a late-arriving VM callback can no longer touch freed memory.

Bad (implementation detail, names internals):

Hardened AppleVmBackend. Replaced usize VM pointer with Arc<AtomicPtr<VZVirtualMachine>> and wrapped VZ calls in objc2::exception::catch so NSException becomes Err(String) instead of triggering abort().