A good changelog format has five line items per release, grouped by type, ordered from new features to bug fixes, with a date in ISO 8601 and a version that follows semantic versioning. It is the only document your users read that proves the product is still moving. That is the practical answer. The strategic answer is that the changelog is the most underrated sales document in your company, and most teams write it like a developer diary. This post is for the founder, PM, or developer who wants the format that actually works for retention, SEO, and team morale.
This post assumes you ship software on a regular cadence, that you have a public-facing changelog (or are about to), and that you want the version your users will actually read.
Table of contents
- Why the changelog is the cheapest sales doc you own
- The five-line format that survives every team size
- The grouped-by-type structure (Added, Changed, Fixed, Removed, Security)
- The date format that does not cause arguments
- What goes in each release (the curated-not-dumped rule)
- The Unreleased section that buys you weekly breathing room
- What to leave out (and why commit logs are not a changelog)
- The hosting decision (CHANGELOG.md, GitHub Releases, or both)
- The opinion this post is built on
- FAQ
Why the changelog is the cheapest sales doc you own
A changelog is the only document your users see on a regular cadence that has all four of these properties:
- It is read voluntarily. Users opt in. They have already decided to follow your release. The next-best document — release notes in an email — has to fight the spam filter and the unsubscribe button.
- It is read at peak intent. The user is in the product, looking at the new version, deciding whether to upgrade. Every other marketing document fights for attention; the changelog has it.
- It proves velocity. A changelog with three years of weekly entries is the most convincing argument for “this team is still shipping” you can put on a landing page. A landing page with a “Built for the long term” tagline does not prove velocity. A changelog does.
- It is a moat for technical buyers. Engineering managers, technical founders, and infrastructure buyers read changelogs as part of vendor due diligence. If your changelog is current, you pass the test. If your changelog is empty, you fail.
The teams that recognize this write changelogs the way they write landing pages — with the user in mind, with clear structure, with a real editorial eye. The teams that treat the changelog as a developer diary produce entries that read like commit messages and get skimmed for the version number only.
The format below is the version that has the best retention numbers, the best SEO surface, and the lowest authoring cost. It scales from a solo founder shipping weekly to a hundred-engineer team shipping daily.
The five-line format that survives every team size
The format that survives every team size is the one used by Keep a Changelog, which is the de facto standard. A release entry looks like this:
## [2.4.0] - 2026-06-13
### Added
- Webhook signing with HMAC-SHA256, configurable per endpoint.
- New `priority` field on the API for job ordering.
- Spanish, French, and German UI translations.
### Changed
- Default rate limit raised from 60 to 120 requests per minute.
- The `legacy` flag is now a deprecation warning instead of a hard error.
### Fixed
- CSV exports with more than 50,000 rows no longer truncate at 49,999.
- Login form was double-submitting on Safari mobile.
### Removed
- The deprecated `/v1/users` endpoint returns 410 Gone.
### Security
- Patched CVE-2026-1042 in the image upload path.Five groups. New at the top. Removals and security at the bottom. Each line is a complete sentence that a user can read without context. The version number and ISO date are on the header line.
This is the format. There is no better format. There are dozens of variations — semicolons instead of bullets, subheadings instead of grouped headers, prose instead of bullets — and they all do worse on at least one of the four properties above.
The grouped-by-type structure (Added, Changed, Fixed, Removed, Security)
The five group types are not arbitrary. They are the only five categories a user needs to make an upgrade decision.
Added. New features, new endpoints, new configuration options, new translations, new payment methods. The reason a user upgrades.
Changed. Existing behavior that has changed. Not new features, but modifications to old features. The category that catches the “wait, did this used to work?” question.
Fixed. Bug fixes. The reason a user with a specific bug upgrades. The category that is most likely to make a user feel seen.
Removed. Deprecated features that have been removed. The category that prevents “this broke my integration” tickets.
Security. Security fixes. The category that has to be visible for compliance reasons.
Two of these are worth highlighting:
- Changed is the most underrated. Users do not upgrade for bug fixes alone. They upgrade when something they care about has changed in a way they want. Surfacing the change with a clear sentence is the cheapest way to retain an upgrade-motivated user.
- Security is the most legally important. A security fix that is not in the changelog is a security fix the user has to discover themselves. For any product that processes personal data, the security section is a compliance artifact as much as it is a documentation artifact.
The order of the groups is not arbitrary either. Added is at the top because users want to know what they get. Security is at the bottom because users want to know what is fixed but rarely need to act on it immediately.
The date format that does not cause arguments
The date format is ISO 8601: 2026-06-13. Year, month, day, in that order, with hyphens. The reason is not aesthetics. The reason is that every other date format causes arguments.
06/13/2026 is American. 13/06/2026 is European. 13-Jun-2026 is ambiguous about the year. June 13, 2026 is American-prose. Every one of these has caused a heated Slack thread on a release day. 2026-06-13 is the only format that does not.
The version-and-date header is also the anchor for the cross-link from your docs, your release notes, your GitHub release tag, and your API documentation. The version 2.4.0 paired with the date 2026-06-13 is a unique identifier that survives every kind of refactor.
What goes in each release (the curated-not-dumped rule)
The rule is that every line in the changelog has been read by a human and judged worth a user’s attention. No raw commit dumps. No auto-generated “merged 47 pull requests” entries. No “various improvements and bug fixes.”
The test for whether a line belongs in the changelog is whether a user would be surprised, pleased, or relieved to see it. The user is not surprised by “merged 47 PRs.” The user is surprised by “CSV exports with more than 50,000 rows no longer truncate at 49,999.” That is a line.
The discipline is also what scales the changelog across team sizes. A solo founder can keep the discipline because they are the only editor. A hundred-engineer team keeps it because the changelog owner is the bottleneck, not the contributors. The owner reads the PRs, picks the user-visible ones, writes the sentence, and rejects the rest.
A useful exercise: take the last three months of changelog entries and ask, for each one, “would a user who has never met me be able to understand what changed and why they care?” If the answer is no, rewrite the line. If the answer is still no after a rewrite, delete the line.
The Unreleased section that buys you weekly breathing room
The pattern that prevents the changelog from becoming a release-day scramble is the Unreleased section at the top of the file:
## [Unreleased]
### Added
- Webhook signing with HMAC-SHA256, configurable per endpoint.
### Changed
- Default rate limit raised from 60 to 120 requests per minute.
### Fixed
- CSV exports with more than 50,000 rows no longer truncate at 49,999.When a release is cut, the Unreleased section is moved into a new dated version section:
## [2.4.0] - 2026-06-13
### Added
- Webhook signing with HMAC-SHA256, configurable per endpoint.
...
## [Unreleased]
### Added
- New `priority` field on the API for job ordering.The pattern lets engineers add to the changelog as they merge, without waiting for release day. The release-day work becomes “rename the section and add the date” instead of “remember everything we shipped.”
It also lets users see what is coming. A user who reads the changelog before upgrading sees both what shipped and what is in flight. The trust signal is real: “this team is transparent about the roadmap.”
What to leave out (and why commit logs are not a changelog)
Three things that do not belong in the changelog, and why.
Commit log diffs. “Fixed typo in docs” is a commit. It is not a changelog entry. The user does not care. The exception is when a typo fix is in user-visible docs and is genuinely worth a “we cleaned up the getting started guide” entry, but that is a rewrite, not a dump.
Refactors. “Refactored the auth module” is a changelog entry for engineers. For users, the question is “does my workflow still work?” If yes, the refactor does not belong. If the refactor changes a public API, it belongs under Changed with a sentence about what the user has to do differently.
Internal tooling. “Migrated CI from Jenkins to GitHub Actions” is great for the team retrospective. It is not a changelog entry. The user does not care, and including it trains the team to think of the changelog as a development diary.
The principle is the same: the changelog is for users. Anything that is for the team belongs in the team channel.
The hosting decision (CHANGELOG.md, GitHub Releases, or both)
Three hosting options, with the tradeoffs.
CHANGELOG.md in the repo. The file lives at the root of the repository. Every PR can edit it. Every release tag can reference it. The file is the source of truth. The downside is that non-engineers cannot easily contribute. The upside is that engineers will actually update it.
GitHub Releases. A release is a Git tag with a description. The description can be the same content as the changelog entry. The upside is that GitHub’s release UI is friendlier than a raw Markdown file, and users can subscribe to releases by watching the repo. The downside is that the content lives in GitHub, not in the repo, and a team that switches hosting loses the history.
Both. The right answer for most teams. The CHANGELOG.md is the source of truth, written and edited by engineers. The GitHub Release is a copy, generated from the changelog at release time. The two stay in sync because the same person writes both.
A useful pattern: the release script reads CHANGELOG.md, extracts the latest version’s section, and uses it as the body of the GitHub release. The script is 30 lines. The discipline is that the script is the only way to cut a release.
For a PaaS like RunxBuild, the changelog can ship as part of the platform’s release process — the changelog template lives in the docs and is updated per release. The same script that deploys the service updates the changelog.
The opinion this post is built on
The opinion is that the changelog is a sales document, not a developer diary. The format above is the one that produces a sales document. The teams that recognize this write changelogs that are read, indexed by search engines, and quoted in customer pitches. The teams that do not recognize this write changelogs that are skipped.
A useful exercise: take the last release’s changelog entry and ask, “if a prospect found this on Google, would they be more or less likely to buy?” If the answer is less, rewrite it. The changelog is the only document on the internet that proves you shipped what you promised. It should sell the promise.
FAQ
What is the standard changelog format?
The Keep a Changelog format: each release has a version and ISO date in the header, followed by five groups (Added, Changed, Fixed, Removed, Security) of bullet-pointed lines. Each line is a complete sentence that a user can read without context.
What is the best changelog format for a small team?
The Keep a Changelog format. It scales from a solo founder to a hundred-engineer team. The discipline is the same: each line is curated by a human, grouped by type, ordered from new to removed.
What is the difference between a changelog and release notes?
Release notes are the curated subset of the changelog that goes to a wider audience (email, blog, social). The changelog is the canonical record of every change. Release notes draw from the changelog, not the other way around.
Should I follow Semantic Versioning in my changelog?
Yes. The version number in the changelog header is the contract with the user. Major version for breaking changes, minor for new features, patch for bug fixes. The changelog is the documentation of the contract.
What date format should I use?
ISO 8601: 2026-06-13. Year, month, day, in that order, with hyphens. Every other format has caused arguments on a release day. ISO 8601 does not.
Should I include security fixes in the changelog?
Yes. Security fixes have a dedicated Security group at the bottom of each release. The section is required for compliance and user trust. Omitting a security fix trains users not to read the changelog at all.
Where should the changelog live?
CHANGELOG.md at the root of the repository, mirrored to GitHub Releases at release time. The repo file is the source of truth. The GitHub Release is a copy. A release script keeps the two in sync.
What is the Unreleased section?
A section at the top of CHANGELOG.md for changes that have been merged but not yet released. At release time, the section is renamed to the new version and a date, and a fresh Unreleased section is created above it.
How long should each line be?
One sentence. Long enough to be specific, short enough to be scanned. “CSV exports with more than 50,000 rows no longer truncate at 49,999” is the right length. “Various improvements to the export pipeline” is the wrong length.
Can I auto-generate the changelog from commit messages?
You can, but the output is worse than curated entries. Auto-generated lines read like commit messages. The discipline of having a human pick the user-visible changes is what makes a changelog read.
Should I link to PRs or issues in the changelog?
Optional. A short tag at the end of the line ([#1234]) is fine. Long prose with author names and merged-by tags is noise. The user wants the change, not the ceremony.
What about GitHub Releases vs the changelog file?
Use both. The changelog file is the source of truth. The GitHub Release is a friendly UI for the same content, with notifications. A release script copies the changelog section into the GitHub release body.
How does RunxBuild use changelogs?
Each RunxBuild release follows the Keep a Changelog format. The changelog is the user-facing record of every deploy, and the hosting calculator tracks the cost impact of the changes that ship. The platform’s own release notes template is the public version of the same pattern.