Start With the Pull Request Title
A pull request title is a single line of text that sits on top of a set of code changes. It is the first thing a reviewer reads, and it is often the only thing a reader of your changelog will ever see. Before you write any release notes, gather the titles of the pull requests merged since the last release and put them in one list. That list is your raw material.
Newcomers sometimes open a changelog file and try to remember what happened over the past few weeks. Memory is a poor source. The pull request titles are already written down, they were reviewed by someone else, and they follow the same order as the work itself. Treat them as a set of small, honest notes from your past self and your teammates.
Read the list once without editing anything. Notice which titles make sense on their own and which ones need a translator. A title like Fix login redirect tells a reader what happened. A title like JIRA-482 patch tells them almost nothing. That gap is the work ahead of you.
Run a Checklist Before the Green Light
Good changelog writing starts long before the release. It starts when a pull request is opened. If your team agrees on a few rules for titles, the changelog almost writes itself later. Bring this checklist to your next pull request review.
- Start with a verb in the present tense. "Add", "remove", "fix" and "rename" describe an action a reader can picture.
- Name the feature, not the ticket. Ticket numbers belong in the tracker; the changelog is for people without access to it.
- Keep it to one idea. If a pull request does two unrelated things, split it. Two clear titles beat one confusing sentence.
- Say who is affected when it matters. A change to the billing export means something different from a change to the docs site.
- Leave out the implementation detail. "Use memoization in the config loader" is code review language. "Stop reloading config on every request" is changelog language.
None of these rules require extra tooling. They cost a few seconds during review, and they save a long editing session later. If a title fails the checklist today, ask the author to fix it now while the change is still fresh in everyone's mind.
Sort Titles Into Changelog Buckets
Once the titles are clean, group them. Most changelogs use a small number of buckets so a reader can scan for the kind of news they care about. A simple set works for nearly any project.
- Added for something new that a reader can start using.
- Changed for behaviour that is different from before.
- Fixed for bugs that no longer happen.
- Deprecated for features that still work but will go away.
- Removed for things that are gone, and security for anything that closes a vulnerability.
Move each title into exactly one bucket. If a change seems to belong in two, pick the bucket that matters most to the person reading the release, and mention the rest in the sentence you write. Sorting also shows you the shape of the release: a list full of fixes reads very differently from a list full of new features, and your opening sentence should reflect that.
Rewrite Jargon So a Newcomer Understands It
The bucket headings give the reader a map. The sentences inside each bucket are where plain language earns its keep. Your reader is a newcomer to your project, not a newcomer to software. They know what an API is; they do not know your internal service names, your file paths, or the story behind the refactor.
A quick test: read the line out loud to someone who did not work on the change. If they can repeat back what is different for them, the line is done. If they ask "so what does that mean for me", rewrite it. Describe the effect first, the cause second. "Sessions now survive a server restart" beats "Rework session persistence around the new store" every time.
Watch for these common traps:
- Internal codenames. Replace them with the user-facing feature they refer to.
- Unexplained abbreviations. Spell out acronyms on first use in the release.
- Bare issue references. Keep the number in parentheses if you like, but never make it the whole line.
- Vague verbs. "Improved" and "updated" hide the change. Say what improved and for whom.
Let a Model Draft the First Pass
After a few releases, the workflow becomes mechanical: collect the titles, sort them, rewrite them, paste them into the changelog file. Mechanical steps are perfect candidates for a script. A short command that prints merged pull request titles since the last tag gives you the raw list in seconds, and a simple template keeps the headings consistent.
The rewriting step is where a language model helps most. Paste the sorted titles into a prompt that says who your readers are and asks for one plain sentence per entry. Models are good at turning "Refactor token refresh into middleware" into "Sign-in sessions refresh quietly in the background." Always read the draft before you commit it. The model does not know which internal codename is public, and it will happily invent a detail that never shipped.
If you want to try this without wiring up anything yourself, SwiftRelay is a pay-as-you-go relay for Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and other models, so you can send a small prompt and pay only for the tokens you use. It works with Claude Code, Codex, Gemini CLI and any OpenAI-compatible SDK. The API host is https://api.fastapirelay.com; Claude Code and Gemini CLI take the bare host, and OpenAI SDKs add /v1. A model like Claude Sonnet 5.5 handles the tidy-up pass well, and Gemini 3.8 Flash is a quick choice for a first draft you plan to edit by hand.
Billing is per token, new accounts get a small gift credit, and inviting friends earns 14% of their top-ups. Create a SwiftRelay account and run your next changelog draft through it before the green light.