Question 1

What is the 'Keep a Changelog' convention?

Accepted Answer

A community spec maintained at keepachangelog.com (current version 1.1.0) that prescribes a strict structure: an `[Unreleased]` section at the top, then released versions in reverse-chronological order, each tagged with a date in ISO 8601 format (`YYYY-MM-DD`), and each subdivided into six fixed sections, **Added**, **Changed**, **Deprecated**, **Removed**, **Fixed**, **Security**. The six categories are intentionally broad enough that you almost never need to invent custom ones; the consistency is what makes the file scannable for users who follow many projects.

Question 2

How does this differ from auto-generated changelogs (e.g. semantic-release, conventional-changelog)?

Accepted Answer

Auto-generators parse commit messages, typically [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `BREAKING CHANGE:`), and produce entries mechanically. They're excellent for high-volume libraries with strict commit-message discipline and CI gates that reject non-conforming commits. A hand-written changelog, by contrast, communicates **intent**: what users actually need to know, in plain user-facing language, often grouping a dozen 'tweak: ...' commits into a single coherent bullet. Many projects use both, auto-generated as a first pass, hand-edited for the release that ships.

Question 3

What goes under [Unreleased]?

Accepted Answer

Every change merged to your release branch since the last tagged version. When you cut a release, rename `[Unreleased]` to the new version with the date (`## [1.4.0] - 2026-05-15`), then add a fresh empty `[Unreleased]` at the top of the file. This pattern lets contributors see what's queued for the next release without anyone having to estimate the version number on every PR, and it gives release managers a ready-to-edit draft instead of an empty document at release time.

Question 4

Should I follow Semantic Versioning?

Accepted Answer

If your project is a library consumed by others, yes, [SemVer](https://semver.org/) is the de facto API contract. **MAJOR** for breaking changes, **MINOR** for backwards-compatible features, **PATCH** for backwards-compatible fixes. The `0.x.y` zone explicitly means 'unstable, anything can change'; promote to `1.0.0` only when you're committing to backward compatibility. For applications (web apps, CLIs, end-user products) where there's no public API to break, any scheme works, CalVer (`2026.05.15`, `26.05`) is increasingly common because it communicates recency at a glance.

Question 5

What's the difference between Deprecated and Removed?

Accepted Answer

**Deprecated** = still works in this release, but will be removed in a future version. Always give users (a) a migration path, the replacement API or workflow, and (b) a target version when it will stop working ('will be removed in v4.0.0'). **Removed** = gone in *this* release; you must update before upgrading. Going straight from working to removed without a deprecation window is the most common reason a library gets a reputation for 'breaking changes with no warning.' One full minor/major cycle of deprecation is the typical floor.

Question 6

When should I use the Security category?

Accepted Answer

Any fix for a vulnerability, even when it's not severe enough to publish a formal CVE or GHSA advisory. The category signals to users that **upgrading is more urgent than a normal bugfix**, which affects their patch prioritization. If you do have a public security advisory or CVE number, link it directly in the entry (`Fixed XSS in comment renderer (CVE-2024-XXXXX, GHSA-XXXX-XXXX-XXXX)`). Don't bury security fixes under 'Fixed', users skim, and a missed security update is the worst kind of missed update.

Question 7

Should changelog entries link to commits or PRs?

Accepted Answer

PRs are usually more useful than commits, they carry discussion, scope, a clean diff, and reviewer context. Issue numbers are great for fixes (`Fixed flicker on page load (#1234)`). Avoid raw commit SHAs; they're noise for the reader and don't survive squash-merges. The standard pattern is reference-style links at the bottom of the file (`[#1234]: https://github.com/you/repo/pull/1234`) so the entries stay short and one-link-per-thing remains easy to update.

Question 8

Should I write entries in past or present tense?

Accepted Answer

Past tense, from the user's perspective at the moment they read the release notes ('Added dark mode toggle' not 'Add dark mode toggle' or 'Adds dark mode toggle'). This is the opposite of the imperative-mood convention for commit messages, and the difference is intentional: commit messages describe *what this commit does to the codebase*; changelog entries describe *what changed for the user*. The Keep a Changelog spec itself uses past tense in all its examples.

Question 9

Where should I put the CHANGELOG.md file?

Accepted Answer

At the root of the repository, alongside `README.md` and `LICENSE`. GitHub, GitLab, and npm all auto-link a root-level `CHANGELOG.md` from your package page. Some monorepos put a separate changelog per package (`packages/foo/CHANGELOG.md`); this is correct for npm publishing because each package version has its own history, but it requires tooling to maintain, typically [Changesets](https://github.com/changesets/changesets) or [Lerna](https://lerna.js.org/) handles the splitting and versioning.

Question 10

Do I have to keep a changelog if I'm already using GitHub Releases?

Accepted Answer

GitHub Releases and CHANGELOG.md serve overlapping but different audiences. **GitHub Releases** is for users who land on your repository page; it's the canonical announcement, supports rich Markdown, lets you attach binaries, and triggers notifications for watchers. **CHANGELOG.md** is for users who get your package via npm/JSR/cargo/pip, they may never visit your GitHub. It's also versioned alongside the code, so users on older versions can read the changelog *as it existed at their version*. Most healthy projects maintain both, with the GitHub Release body essentially mirroring the new CHANGELOG.md section. Tools like `gh release create --notes-file CHANGELOG-EXTRACT.md` automate this.

Question 11

How do I retroactively backfill a changelog for an existing project?

Accepted Answer

Don't try to recreate every commit, you'll burn out and abandon it. Instead, walk `git tag` in reverse chronological order. For each tag, look at the diff against the previous tag (`git diff v1.2.0 v1.3.0 --stat` and `git log v1.2.0..v1.3.0 --oneline`) and write a *summary*, 3-8 bullets describing what users would have noticed. Anything before some recent date can become a single 'Earlier versions, see git history' line. Start fresh from the next release with proper entries-as-you-go. Backfilling perfectly is much harder than maintaining; aim for 'good enough to be useful' on the past, 'rigorous' going forward.

Question 12

What standards does Changelog Generator validate against?

Accepted Answer

Changelog Generator checks compliance with Keep a Changelog format, Semantic Versioning 2.0.

Question 13

What are the limitations of Changelog Generator?

Accepted Answer

Does not parse Git history, generates from manual input Does not integrate with GitHub/GitLab release APIs Format is opinion-based

Category	User Persona Impact	Commit Mapping (Conventional)	Priority
Security	Critical Audit	`fix: (security)`	High
Removed	Breaking Change	`BREAKING CHANGE:`	High
Added	Feature Discovery	`feat:`	Medium
Fixed	Reliability Check	`fix:`	Medium
Deprecated	Migration Notice	`refactor: (deprecate)`	Low

Changelog Generator

Privacy note

How to Use Changelog Generator

Paste Git Log

Configure Format

Generate

Changelog Generator: the essentials

Key points

What is Changelog Generator?

Frequently Asked Questions

Technical Deep Dive

Changelog Generator

Instant Generation

Fine-Grained Control

Verified Output

01 Changelog Categorization Matrix

02 Release Documentation Pipeline

Runs 100% in your browser

You Might Also Need

Bitwise Calculator

Favicon Generator

Graph Plotter

Lorem Ipsum Generator