Keep a Changelog vs GitHub Releases

Keep a Changelog is a convention, not a tool: a human-readable CHANGELOG.md with an entry for every version, the latest first, dates as YYYY-MM-DD, and changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security.

GitHub Releases are a GitHub feature: one page per git tag with Markdown notes, optional binary attachments, and flags for pre-release and latest release. GitHub can generate the notes from merged pull requests. For the general difference between the two kinds of document, see changelog vs release notes.

Version 2.0.0, dated 7 June 2026, is the first major revision. Its own changelog says it “breaks the guidance, not the format”: the six types of change, YYYY-MM-DD dates, Unreleased and [YANKED] are unchanged, so a changelog written to 1.1.0 stays valid. The changes that matter here:

• Release notes come from the changelog. The old “What about GitHub Releases?” answer became “Is a changelog the same as release notes?”, and covers any code host. A changelog is “the complete, ongoing record”; release notes are “an announcement for a single release”.
• Generated notes are a starting point. Release notes a host generates are “stored in the host's database, not your repository”, so Keep a Changelog says to keep CHANGELOG.md as the canonical record and generate release posts from it.
• Breaking changes are marked in place. A short **Breaking:** marker on the entry, usually under Changed or Removed, instead of a separate section.
• Every version links to its diff. Version headings resolve at the bottom of the file to a compare view against the previous version, and [Unreleased] compares the latest tag to HEAD.
• A pinned preamble. Link the exact version you follow, such as https://keepachangelog.com/en/2.0.0/, “so it stays accurate as this page changes.”

Checked on 12 November 2026: keepachangelog.com's front page still opens 1.1.0 by default, and 2.0.0 lives at keepachangelog.com/en/2.0.0. The 1.1.0 tagline, “Don't let your friends dump git logs into changelogs”, was retired for “Clearly document the evolution of your projects.” The CHANGELOG.md format guide walks through the whole 2.0.0 format.

• A library or package published to a registry: both. CHANGELOG.md is the record, the release is the announcement.
• An app or CLI that ships binaries: GitHub Releases are where downloads live. Keep a CHANGELOG.md too if people skip several versions at once.
• A project without tags or releases: a CHANGELOG.md alone is fine.
• Product updates for non-developers: neither is ideal. Use a hosted changelog page people can find without a GitHub account.

Pick one source of truth and generate the other. Keep a Changelog 2.0.0 recommends the changelog: “Keep the changelog as the record, and write the release notes from it rather than maintaining two.”

• CHANGELOG.md first: write the entry in your release pull request, then publish that section as the GitHub release. In Keep a Changelog's words, “a small script can extract that section and create the release without anyone retyping it”; the one below does.
• Tool-driven: release-please opens a release pull request that updates CHANGELOG.md and creates the GitHub release when you merge it. semantic-release publishes the GitHub release and, with its changelog plugin, writes CHANGELOG.md. Both read Conventional Commits; see release notes from commits, and semantic-release vs release-please vs Changesets to choose a tool.
• GitHub first: set up categories in .github/release.yml, click Generate release notes, add highlights above the list, then copy the result into CHANGELOG.md, which stays the record. No labels yet? Generate a draft from git instead.

# The 1.4.0 section of CHANGELOG.md, without its heading
awk '/^## \[1\.4\.0\]/{found=1; next} found && /^(## |\[[^]]+\]: )/{exit} found' CHANGELOG.md > notes.md

# Create the release for the pushed tag v1.4.0 with those notes
gh release create v1.4.0 --title "1.4.0" --notes-file notes.md --verify-tag

Replace 1.4.0 with your version. The awk line stops at the next version heading or at the link references at the bottom of the file. With --verify-tag, the GitHub CLI stops instead of creating a tag that hasn't been pushed. To run this on every tag without maintaining a script, the free LogPulse GitHub Action does the same in a workflow: it finds the section for the tag, puts breaking changes first, and falls back to the commits since the last tag when there's no section. It's one workflow step, uses: kalmwerk/release-notes-action@v1 (on GitHub).

changelog:
  exclude:
    labels:
      - ignore-for-release
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: New features
      labels:
        - enhancement
    - title: Bug fixes
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

"*" is a catch-all for pull requests that didn't match any of the earlier categories. Categories only work if your team labels pull requests consistently. A Breaking changes heading is fine in a release, which is an announcement; in CHANGELOG.md, mark each breaking entry in place.

Keep a Changelog 2.0.0 rules out a special format for machines: “There is no separate machine format, and there will not be one: this page is the format.” A consistent changelog is what tools and agents parse well: version headings, the six types and a **Breaking:** marker on every breaking entry. Paste your CHANGELOG.md or a GitHub releases URL into the free changelog-to-JSON converter to see what an agent can extract: versions, dates, breaking changes, migration steps and deprecations.