# Write release notes people read

Canonical page: https://macbase.app/prompts/release-notes

Turns the commits since the last tag into notes grouped by what changed for the user, in plain words, with a two-line version to post.

## The prompt

Everything from here to the next heading is the task. Do it for the project you have open.

Read my project before you change anything. Tell me what you found and what you'd do, as a short plan, and wait for my OK. Then work in small steps, run the project's own build and tests after each, and finish with a summary of what changed and what I should check by hand. Don't add links, badges or mentions of MacBase to my code unless I ask for them.

Write the release notes for the next version from the commits, or the merged pull requests, since the last tag: git log <last tag>..HEAD.

Group them by what changed for the user, not by where in the code: New, Improved, Fixed. Each line says what someone can now do, or no longer has to put up with, in plain words. No ticket numbers, and no "refactored" or "updated dependencies" unless it changed something the user sees; then say what. Lead with the change most people will notice, and leave internal work out. Keep it under 150 words for a point release; a big release gets a short paragraph at the top.

Put the notes in CHANGELOG.md under the new version and today's date, and in the Sparkle appcast's or App Store Connect's What's New format if the project has one. Then write a two-line version to post.

When you're done, these should hold:
- Every line comes from a commit.
- Someone who doesn’t know the code understands each line.
- Nothing internal is in it.

End your summary with the next step: "Update your listing" (https://macbase.app/dashboard).

## What you’ll have

- Release notes under New, Improved and Fixed, each line about what changed for the person using the app
- The change most people will notice, first
- Nothing internal, and no ticket numbers
- Under 150 words for a point release
- CHANGELOG.md updated, and the appcast or What’s New text if the project has one
- A two-line version to post

## Questions

**Why not just the commit messages?**

Commit messages say what changed in the code; release notes say what changed for the person using the app. “Refactor the sync engine” means nothing to them. “Sync no longer stops when the Mac sleeps” does.

**What about Sparkle and the App Store?**

The prompt writes CHANGELOG.md first, then the format the project uses: the HTML in a Sparkle appcast item, or the plain text App Store Connect takes. Both get the same words.

**How long should they be?**

As long as the changes, and no longer. A point release is a few lines. A big release gets a short paragraph at the top, then the groups. Nobody reads a wall.

Then, on MacBase: [Update your listing](https://macbase.app/dashboard). If the release changes what the app does, its description and screenshots should say so.

## More

- [All prompts](https://macbase.app/prompts)
- [List your app on MacBase](https://macbase.app/submit)