Release notes: how to write them from your Git history
How to write release notes users can act on: read the Git history, keep what users notice, put breaking changes first and trace every line to a commit.
Free app. Runs on your Mac with the Claude or Codex plan you already have.
What good release notes are
Release notes tell the people who use your software what changed in a release and what, if anything, they must do about it. They are written from the Git history between two versions, but they are not that history. A commit says what a developer changed. A release note says what a user will notice.
The method below is how an experienced technical writer turns a range of commits and pull requests into notes a customer, an administrator or a support team can read in two minutes. It works whether the team writes careful commit messages or terse ones, because every unclear change is read before it is described. Each step says what to do and why, then how 10folds carries it out.
What it does for the business
- Users upgrade with confidenceWhen breaking changes and required actions sit at the top, administrators can plan an upgrade instead of discovering problems after it. Fewer surprises means fewer rollbacks and fewer urgent tickets.
- Support and sales know what shippedClear notes give the support team answers before the questions arrive, and give sales a short list of improvements to mention to customers who asked for them.
- Work that shipped gets seenFixes and small improvements disappear without a written record. Notes make a steady release rhythm visible to customers and to the rest of the company.
- A changelog you can trustBecause every line is traced to a commit, anyone can check a claim later. The changelog becomes a reliable record of when each behavior changed.
Release notes, step by step
Collect every change in the release range
Release notes start with an exact range, because a vague range produces vague notes.
What to do
- Find the previous release tag and the revision you are about to ship.
- List every commit between them with git log, including the pull request titles and bodies in merge commits.
- Group commits by type if the team writes Conventional Commits (feat, fix, perf and so on).
- Cancel any commit that was reverted inside the same range.
- Look at the existing changelog and copy its headings and tone.
Why
A list built from memory always misses changes, and a range that starts at the wrong tag repeats or drops a whole release. Reverted work is the most common false announcement: the feature appears in the log twice and in the product not at all.
Decide what users need to know
A change belongs in the notes when someone outside the team would notice it.
What to do
- Keep new features, behavior changes, visible fixes, performance users can feel, security fixes, deprecations and removals.
- Leave out refactoring, tests, CI changes and dependency bumps with no visible effect.
- Judge commits with unclear subjects by reading their body and the files they changed.
- Merge several commits that deliver one change into one line.
- For each breaking change, find the action the reader must take in the commit or the changed documentation.
Why
Readers stop reading notes that list internal work, and then miss the one line that matters to them. Merging related commits avoids five lines for one feature. A breaking change without an action tells people something will break and leaves them to work out what to do.
Write the notes for the reader
Write what the user can now do, in the words the user would use.
What to do
- Open with a one-line summary of the release.
- Put "Action needed" first for breaking changes and removals, then New, Changed, Improved, Fixed, Security, Deprecated, Removed.
- Write each line in plain words and the present tense, such as "Export project reports as PDF".
- Mention side effects users may notice, such as a setting that moved.
- End each line with its pull request or issue reference.
Why
A fixed order works like a release notes template: readers learn where to look for what affects them. Plain wording matters because commit subjects are written for developers. A reference on every line lets a curious reader or a support agent find the detail in one click.
Check every line against the history
A release note that claims more than the commits show is a promise nobody made.
What to do
- Confirm each line maps to at least one commit in the range.
- Confirm nothing reverted is announced.
- Confirm every breaking commit appears under "Action needed" with a stated action.
- Check that no user-visible change was dropped without a reason.
- Check references, and cut wording that overstates what changed.
Why
Errors in release notes are expensive because customers act on them. A missed breaking change causes outages, and an overstated fix causes support tickets from people who still have the problem. A second reader catches what the writer has stopped seeing.
Hand over the notes
Publishing is a decision, so leave it with the person who owns the release.
What to do
- Lead with the breaking change if there is one, otherwise the most valuable change.
- Share what was left out and why with anyone who asks about a missing item.
- Tell other teams about side effects that will reach them.
- Choose the version number, then publish to the changelog, release page or customer email.
Why
The person who owns the release knows the audience, the timing and whether the version number fits the company's promises. A short list of exclusions answers "why is my fix not mentioned" before it is asked. Keeping publication as a separate, human step also means a draft can be corrected before any customer reads it.
Common mistakes
- Pasting the git logCommit subjects are written for developers, and users skip them.
- Burying breaking changesA required action in the middle of a list of fixes will be missed.
- Announcing reverted workA feature that was added and then removed in the same range never shipped.
- Listing internal workRefactors and test changes push the useful lines out of sight.
- Inventing the upgrade stepIf neither the commit nor the docs say what to do, ask the author before you publish.
What a good result looks like
- A one-line summary a support agent could repeat.
- Breaking changes first, each with a clear action.
- Lines in plain, present-tense language a user understands.
- A pull request or issue reference on every line.
- A separate list of what was left out, with reasons.
And then what? Using the result
- Decide the version number from the semantic versioning note.
- Paste the notes into your changelog and your release page.
- Send the Action needed section to customers who integrate with you.
- Share the side effects with support before the release goes out.
- Ask the team to write Conventional Commits if grouping took a lot of reading.
When to run it
- Before every releaseRun it on the range you are about to tag, so the notes are ready when the release is.
- When the changelog has fallen behindRun it once per missed release range to rebuild a record of what changed and when.
- Before a customer email or announcementThe notes give marketing and sales an accurate list of what shipped, with references for anyone who wants detail.
- When a release contains breaking changesThe check that every breaking commit has a stated action matters most when upgrades can fail.
Questions people ask
How do you write release notes?
Fix the range between two versions, list every change in it, keep only what users would notice, put breaking changes first with the action needed, write each line in plain words and check every line against its commit.
How do you write release notes from git commits?
Read the commits and pull requests between the last tag and the new revision, group them by type, drop internal and reverted work, merge commits that deliver one change and rewrite each as what the user now sees.
What should release notes include?
A short summary, breaking changes with the action required, new features, changes, fixes, security fixes, deprecations and removals, each with a reference to the pull request or issue.
What is the difference between a changelog and release notes?
A changelog is the running record of changes across all versions, kept in the repository. Release notes describe one release for its readers. Many teams paste each release's notes into the changelog. The same traced lines serve both, so write them once.
Does it work without Conventional Commits?
Yes. Commits are then marked unclassified, each is judged from its subject, body and changed files, and the notes say that grouping was done by reading. Squashed or merge-only history is read from the pull request titles and bodies in the merge commits.
Does it change my repository or publish anything?
No. It runs no command that changes the repository and publishes nothing. You choose the version and publish the notes yourself.
More jobs in Developers
Write release notes from Git history, on your own Mac.Free app. Runs on your Mac with the Claude or Codex plan you already have. Your files stay on your computer.
Download for Mac