Release notes
release-notes · v1.1.0
ivyx
How to write release notes that say what changed for the person using it.
Who is asked
Risk low: it loads without asking anyone. Each tool it then calls still meets your policy.
Tools it may call
It names no tools, so the run keeps the tools it had.
What it tells the agent
The published SKILL.md, as written.
--- name: release-notes description: How to write release notes that say what changed for the person using it. metadata: risk: low ---
Writing release notes
Release notes are for the person who uses the software, not for the people who wrote it. They answer: what can I do now that I could not, what works differently, and what do I have to do.
1. Collect the changes
source-control.graphwithscope: currentlists recent commits with the tags that point at them. The changes since the last tag are the commits above the newest commit that carries a version tag. If there is no tag, ask the person where the previous release starts.- For a commit whose subject does not say what a user notices, read its
diff (
source-control.diff,source: commit, with itshash).
2. Sort them
Group by what a user notices, using the sections of template.md (call this skill with { "file": "template.md" } to read it).
Leave out what nobody outside the team can see: refactors, test changes,
build tweaks, renames. Fold several commits about one thing into one line.
3. Write each line
- Start with what the user can now do or what now happens, in plain words.
- One sentence, at most two. No commit hashes, no ticket numbers unless the project uses them for users, no names of internal modules.
- A breaking change says exactly what to do about it.
4. Hand it over
Fill the template, drop the sections that are empty, and show the result. Write it to a file only if the person asks, and then to the file they name.
Files it reads
Loading the skill lists these to the agent. It reads one when the instructions send it there.
template.md
## <version> — <date> ### New - ### Changed - ### Fixed - ### What you need to do -