sections with

subpoints, lists, etc. So we need multiple sections. We need to include the opening block exactly:

Changelog vs git log: what Keep a Changelog actually requires

Changelog vs git log: what Keep a Changelog actually requires

Teams often paste git log into a release and call it done. Keep a Changelog is explicit: changelogs are for humans, not machines, and commit-log diffs are full of noise (merges, obscure titles, internal refactors).

Teams often paste git log into a release and call it done. Keep a Changelog is explicit: changelogs are for humans, not machines, and commit-log diffs are full of noise (merges, obscure titles, internal refactors).

Why raw git log fails users

When a team copies the output of git log straight into a release note, the result is a wall of text that confuses anyone who is not looking at the repository.

Three patterns make the log noisy:

• Merge commits that appear every time a feature branch is rebased or a pull request is merged. These commits carry no functional change but add lines like Merge branch 'feature/x' into main.
• Commit subjects that are written for developers, not for end users. Examples: fix typo in README, rebase onto upstream, update dependency hash. Such messages do not tell a person what changed in the product.
• Internal refactor commits that touch many files but keep the public API identical. A large diff may show dozens of renamed variables or extracted methods, yet the user‑visible behavior stays the same.

Because the log mixes signal and noise, a reader must spend time filtering out the irrelevant parts. In practice, most people skip the note entirely or treat it as a debug dump, which defeats the purpose of communicating upgrades.

What Keep a Changelog actually asks for

The format is deliberately simple: a chronological list of versions, each with a dated block of entries grouped by type.

Core elements

• A header line with the version number and release date, e.g. ## [2.3.0] - 2024-09-01.
• Sections inside the version block such as Added, Changed, Deprecated, Removed, Fixed, Security.
• Each entry is a single sentence that describes a notable difference for a person who installs or upgrades the software.
• An optional Unreleased section at the top for work that is completed but not yet shipped.

Keep a Changelog 2.0 adds a recommendation to state the versioning scheme you follow (usually SemVer) and to keep the file in the repository root as CHANGELOG.md.

Separating changelog from release notes

Keep a Changelog 2.0 draws a line between the ongoing record and a single‑release announcement.

Why the split matters

• The changelog is a permanent, append‑only history that anyone can audit at any time.
• A release note (or blog post) is a temporary marketing piece that can be rewritten, translated, or tailored to a specific audience.
• Maintaining two separate sources prevents contradictions: the changelog never gets softened for hype, and the announcement never omits a breaking change that appears in the log.

My workflow is:

1. After a pull request is merged, I add a short line to the Unreleased section under the appropriate heading.
2. When I decide to cut a release, I copy the Unreleased block, give it a version header, and clear the Unreleased area.
3. I then write a brief blog post or email that pulls the most important items from that block and adds context such as upgrade steps or a short demo video.

SemVer signals breakages; the entry must still say so

Under Semantic Versioning, a major version bump indicates an incompatible API change, but the number alone does not tell a reader what broke.

Keep a Changelog asks you to make the breaking nature explicit in the entry.

How I mark a breaking change

• I start the sentence with the word Breaking: followed by a concise description.
• If the migration steps are long, I add a link to a separate migration guide after the sentence.
• I keep the entry in the Changed or Removed section, depending on whether the API was altered or deleted.

To illustrate the relationship between version bump, section, and required wording, here is a table I use when I train new contributors:

Automation is a draft, not a finished changelog

Tools that parse Conventional Commits or analyze PR labels can produce a first pass of entries.

What the automation gives me

• A list of commits grouped by type (feat, fix, docs, etc.) based on the conventional‑commit prefix.
• Suggested section headings (Added, Fixed, etc.) that match the Keep a Changelog categories.
• A raw sentence built from the commit subject, sometimes cleaned of issue numbers.

What I still have to do

• Read each suggested entry and decide if it is notable enough for a user.
• Rewrite the sentence in plain language that focuses on the effect, not the internal implementation.
• Combine multiple small commits that together affect the same feature into a single, clearer entry.
• Add a Breaking: prefix when the change alters the public contract, even if the commit message did not flag it.
• Check that the version header matches the SemVer decision I made after reviewing the whole set of changes.

What this is NOT

This guide does not promise that every changelog entry will be perfect on the first try.

It does not guarantee that a reader will never miss a breaking change.

It does not claim that the process eliminates all noise from commit history.

It does not assert that automation can replace human judgment.

It does not suggest that you can skip the Unreleased section and still stay compliant with Keep a Changelog.