It's the evening before a release. Someone asks, "Can you put together the release notes?" You open git log and see sixty commits since the last tag. Half of them say fix. A few are merges. You start reading diffs to remember what fix meant.

An hour later you have notes that are accurate but flat — a bullet list of commit messages that nobody outside the team can follow. And you still have to do the changelog.

The fix isn't writing faster. It's making the changelog and the release notes something you generate from work that's already been recorded, and then review.

1. Step One: The Changelog

If you've been running gitaiflow as you work, the summaries it saved are the source. One command turns a date range into a sectioned entry:

gitaiflow --changelog --since "2 weeks ago" --path .

The entry goes under a heading for your project's current version. Re-running it for the same version updates that block in place instead of adding a second one, so you can run it again after a late merge. Commits on your branch that have no summary are added from git, and nothing already written is duplicated.

Sorting is rule-based first, so it's free and works without any AI. The built-in rules know about Breaking Changes, Security, Features, Fixes and more, with extra sections for Python, Go and JavaScript or TypeScript projects. Only bullets that no rule can place go to the AI, and only when there are enough of them.

You can adjust this per repo with a .gitaiflow/changelog.toml file in the same format as the built-in templates. A new section with its own path rule looks like this:

# .gitaiflow/changelog.toml
[[section]]
key = "payments"
title = "Payments"
order = 60
paths = ["payments/**"]

If you never want the AI involved in changelog generation for a repo, set enabled = false under an [ai] table in that same file.

2. Step Two: Release Notes From the Changelog

A changelog is written for the team. A release page is written for people who don't know your project yet. That's the second command:

gitaiflow --release-notes

It reads the changelog entry for the current project version (run --changelog first if that entry doesn't exist yet) and writes RELEASE_NOTES.md at the repo root. The AI produces a title with a specific tagline, a short intro for someone unfamiliar with the project, and a Highlights section that follows the changelog's own sections rather than inventing new themes. Fixes, tests and chores are kept to a short closing mention.

The file has two clear markers, ## Release Title and ## Release Details, so it's easy to paste into a GitHub or GitLab release page. If a .gitaiflow/release_footer.md file exists, its contents become the footer — a good place for install instructions or download links. Otherwise you get a plain "Full Changelog" link.

3. What to Check Before You Publish

Generated doesn't mean finished. Before the notes go out, I read them in this order:

1. Breaking Changes and Security first. These are the sections readers act on, so they must be right.
2. The highlights, for accuracy. They're written by a model from the changelog, so check that each one describes something that really shipped.
3. Edit last. --release-notes always fully overwrites RELEASE_NOTES.md, because it describes the release being cut, not a running history. Make your manual edits after the final run, not before.

Want the Full Picture?

This post covers the release-night flow. For every option and the full configuration reference, see the gitaiflow documentation ↗.

What I'd Tell You If You're Building Something Similar

1. Make release notes a function of the changelog, and the changelog a function of work already recorded. Each layer should be generated from the one below it, not written from scratch.
2. Use rules for sorting and a model for prose. Rules are predictable for classification; a model earns its cost when you need readable sentences.
3. Put the step that overwrites your edits at the end of the pipeline, and edit after it. Otherwise a re-run quietly erases your review.