A release notes generator that writes for people.
ShipNotes is a release notes generator and changelog generator for Claude. It turns the commits between two versions into release notes, a changelog entry or a “What’s new” message. A script collects the commits, reads Conventional Commits and plain messages alike, and groups them as breaking, new, improved, fixed, removed and internal. Claude then writes what changed for the reader, not for the codebase.
01See it work
ShipNotes, in real use.
3 screens from real runs of ShipNotes. Every value shown is what the tool returned; click a screen to open it full size.
02How it works
From commits to notes people read.
Commit messages say what changed in the code. Release notes say what changed for the reader. ShipNotes gathers the first and writes the second.
- 01CollectCommits from the last tag, between two versions or since a date.
scripts/changes.py - 02GroupBreaking, new, improved, fixed, removed and internal, from Conventional Commits or plain messages.
- 03WriteBreaking changes first, each change as its effect, no hype, no numbers without a source.
- 04FormatA CHANGELOG.md entry, a GitHub release, or a short What's new for customers.
03Template
A release notes template that works.
ShipNotes follows this shape. The example is a real run on a 13-commit release of a sample app: five internal commits were left out, and the breaking change leads with what to do instead.
# <Product> <version>
**Breaking:** what stopped working, and what to
use instead.
**New**
- What people can do now that they could not.
**Improved**
- What works better, as the person notices it.
**Fixed**
- What was wrong, now right, in their words.**Breaking:** The old export address,
/api/export.csv, has been removed. Use
/api/shifts?format=csv instead.
**New**
- Staff can offer a shift to a colleague, and the
swap waits for a manager to approve it.
- The API can list a team's shifts for one week.
**Improved**
- The schedule loads a month of shifts in one
request, so it opens faster.
- The team page explains what to do when it is empty.
**Fixed**
- The rest-break warning now covers overnight shifts.
- The week view no longer shows Sunday twice in the
week the clocks change.04CHANGELOG.md
Keep a Changelog, mapped from your commits.
Keep a Changelog is the most common CHANGELOG.md format. ShipNotes maps commit groups onto its sections and leaves internal work out unless you ask for it.
| Commit group | Typical prefixes or first words | Keep a Changelog section |
|---|---|---|
| Breaking changes | feat!:, fix!:, BREAKING CHANGE: | Listed first, usually under Removed or Changed |
| New | feat:, Add | Added |
| Improved | perf:, Improve, Update | Changed |
| Fixed | fix:, Fix | Fixed |
| Removed | Remove, Drop | Removed |
| Internal | test:, ci:, docs:, refactor:, chore:, build: | Left out of customer notes |
05Versions
Semantic versioning and breaking changes.
The groups also tell you which number to raise. ShipNotes puts breaking changes in their own group at the top, so a major change is never buried in what looks like a patch.
| Part | Raise it when | Example |
|---|---|---|
| MAJOR | Something that worked before stops working: a removed endpoint, a renamed option | 2.4.0 to 3.0.0 |
| MINOR | Something new works, and everything old still does | 2.3.0 to 2.4.0 |
| PATCH | Only fixes, nothing new | 2.4.0 to 2.4.1 |
06Install
Install ShipNotes.
Install ShipNotes in Claude Code from the Dude Lemon marketplace, or download it for the Claude apps. Its script needs Python 3.8+ and git.
/plugin marketplace add https://plugins.dudelemon.cloud/marketplace.json/plugin install shipnotes@dudelemonClaude uses the skill when a task matches its description. You can also call it directly with /shipnotes:shipnotes.
07Inside
What is in the skill folder.
SKILL.md- Writing rules (breaking changes first, effect not implementation, no hype) and three formats: Keep a Changelog, GitHub release, and in-app or email notes.
scripts/changes.py- Commits from the last tag, two refs or a date, grouped by type, with pull request numbers, authors and areas. Text or JSON output.
08Ask in your own words
Say what you need. ShipNotes does the exact part.
Claude reaches for ShipNotes when a request matches it. You can also ask for it by name.
- Write release notes for everything since v2.3.0.
- Update CHANGELOG.md for this release.
- Draft the What’s new message for customers this month.
09Works well with
Related tools.
FAQ
ShipNotes, answered
Anything we have not answered here, ask us directly. A senior engineer replies.
Do I need Conventional Commits?
No. The script reads feat:, fix: and the rest when they are there, and sorts plain messages by their first word (Add, Fix, Improve, Remove). Claude reads the diff when a message is too vague to describe.
Are internal changes included?
They are listed separately (tests, CI, refactors, dependency bumps) and usually left out of customer-facing notes.
Can it make up improvements?
No. Every line must come from a change it has read, numbers need a source, and anything unclear is listed as a question for you.
Is ShipNotes free?
Yes. ShipNotes is free and MIT licensed.
How do I install ShipNotes?
In Claude Code run /plugin marketplace add https://plugins.dudelemon.cloud/marketplace.json, then /plugin install shipnotes@dudelemon. In the Claude apps, download https://plugins.dudelemon.cloud/skills/shipnotes.zip and upload it under Customize, Skills.
Can ShipNotes write release notes for a monorepo?
Yes. The script reports the folders each commit touched, so Claude can write notes for one package or app and leave the rest out.