# Draft release notes from git history

Have Claude Code compare two git tags or branches and draft release notes grouped into breaking changes, features and improvements for your readers.

Paste into: **Claude Code**, started in your project folder

## Prompt template

How the builder on the page fills in this template, so you can do the same:

- `{{key}}` becomes the text entered for that field, exactly as typed. Empty text, or text that is only whitespace (spaces, tabs or line breaks), counts as empty: a required field then becomes `[fill in: <label>]` with its label, and an optional field becomes nothing.
- For a choice field, `{{key}}` becomes the text of the chosen option, or of the default when none is chosen.
- Text between `{{#key}}` and `{{/key}}` stays only when that field is not empty; a choice field always counts as filled. The markers themselves are removed, and a marker that stands alone on its line takes its line break with it.
- Each value is inserted once, as it is: `{{…}}` inside a value stays as typed.

```text
Compare {{from}} to {{to}} in this repository and draft release notes.

Read the commit messages, and the merged pull requests if you can reach them. Where a message is unclear, read the diff instead of guessing.

Group the notes under these headings, and leave out any heading that would be empty:
- Breaking changes: what breaks and what readers must do about it
- New features
- Improvements
- Bug fixes

Write for {{audience}}. One line per item, describing the effect rather than the code. Merge related commits into one item. Leave out refactors, CI and dependency updates unless they affect these readers.
{{#style}}
Match the format and tone of {{style}}.
{{/style}}

After the notes, list commits you could not classify, and any change that looks breaking but is not marked as such. Do not commit, tag or publish anything.
```

## Fields

- `{{from}}` (required): Previous release (tag, branch or commit).
- `{{to}}` (required): New release (tag, branch or commit).
- `{{audience}}`: Readers. Choose one:
  - people who use the product, in plain language without code terms (default)
  - developers who use our API or library, with names of changed functions and options
  - our own team, including internal changes worth knowing about
- `{{style}}`: Existing notes to match. Optional. A file whose format and tone the new notes should follow.

This site doesn't run Claude or show model output. Results depend on your input and the model you use.

## When to use this template

- A release is ready and you need a first draft of the notes from what actually changed, not from memory.
- Commit messages are uneven, and you want someone to read the diffs behind the vague ones before they turn into vague release notes.
- You publish notes for more than one audience and want each version written for its readers.

## When not to use it

- The project already generates notes automatically from structured commit messages and they are good enough. Use Claude to polish that output instead.
- The release contains security issues that are not yet disclosed. Keep those out of a draft that may be shared early.
- Your history is mostly squashed commits with titles such as "updates". Claude can read the diffs, but for very large releases the result will need careful checking.

## Why this structure

- Two refs, an older and a newer one, define exactly which changes are in scope, so the notes cover the release and nothing else.
- Reading the diff when a commit message is unclear grounds each item in what changed rather than in how someone summarized it at the time.
- Breaking changes come first and must say what readers have to do. Readers need that part most, and it is the costliest to leave out.
- The readers setting changes the vocabulary and the level of detail, because end users, API developers and your own team need different notes from the same history.
- Asking for unclassified commits and unmarked breaking changes surfaces the items you most need to check, instead of hiding them in the draft.
- The final rule keeps this a draft: Claude does not commit, tag or publish, so nothing goes out before you have read it.

## Example input (fictional)

Previous release (tag, branch or commit):

```
v2.3.0
```

New release (tag, branch or commit):

```
v2.4.0
```

Readers:

```
developers who use our API or library, with names of changed functions and options
```

Existing notes to match:

```
CHANGELOG.md
```

## Follow-ups to send Claude

- Write a short announcement version of these notes for the changelog page: three highlights and a link to the full list.
- For each breaking change, add a before and after code snippet showing how to migrate.
- Check the notes against the diff once more and remove any item that is not actually in this release.

## Common mistakes

- Comparing the wrong refs, for example the release branch against an old main. Check the two refs and the number of commits Claude found before reading the notes.
- Publishing the draft unchanged. Claude can misjudge which changes matter to readers; read every breaking change entry yourself.
- Using developer wording for end users. Choose the readers setting for the people who will actually read the notes.

## Related templates

- [Summarize a document](https://awesomeclaudeprompts.com/prompts/summarize-document/): Turn a long document into a faithful summary: main point first, key points by importance, then decisions and open questions.
- [Code review prompt](https://awesomeclaudeprompts.com/prompts/code-review/): Ask Claude to review a diff for supported issues, ordered by severity, with a location, impact and suggested fix for each finding.
- [Edit a draft for clarity](https://awesomeclaudeprompts.com/prompts/edit-for-clarity/): Make a draft clearer for a named reader while keeping your meaning and voice, with a short list of what changed and why.

## Sources

- [Claude Code docs: Prompt library](https://code.claude.com/docs/en/prompt-library) (Anthropic documentation)
- [Claude Code best practices: Provide specific context in your prompts](https://code.claude.com/docs/en/best-practices#provide-specific-context-in-your-prompts) (Anthropic documentation)

---

Awesome Claude Prompts is an independent project. It is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC.