How to keep a changelog for a Rust crate
crates.io shows your README, not your changelog, and Cargo.toml has no field for one. Below: a copy-paste CHANGELOG.md for a crate, Cargo's rules for breaking changes, four real changelogs to copy, and how to draft entries from commits.
Updated Last checked 9 min readOpen-source libraries and packages
Copy-paste changelog template for a Rust crate
A 0.x release in Keep a Changelog 2.0.0 format. Below 1.0, Cargo treats 0.8 → 0.9 as a breaking upgrade, so this entry carries the two changes crates break most often: a public signature and a removed Cargo feature, each marked **Breaking:** with the fix. Delete the headings you don't need.
# Changelog
All notable changes to this crate are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this crate adheres to [Semantic Versioning](https://semver.org/) as Cargo applies it.
## [Unreleased]
## [0.9.0] - YYYY-MM-DD
Two breaking changes: `Parser::new` takes a `Config`, and the `legacy-api`
feature is gone. The minimum supported Rust version is now 1.85.
### Added
- `Parser::parse_str` parses borrowed input without copying it ([#212]).
### Changed
- **Breaking:** `Parser::new()` takes a `Config`. Replace `Parser::new()` with
`Parser::new(Config::default())`.
- MSRV raised to 1.85 (`rust-version` in Cargo.toml).
### Deprecated
- `Parser::parse_owned`: use `Parser::parse_str`. It will be removed in 0.10.0.
### Removed
- **Breaking:** The `legacy-api` Cargo feature, deprecated since 0.7.0. Delete it
from `features = [...]` in your Cargo.toml and call `Parser::parse_str`.
### Fixed
- `parse_str` no longer panics on empty input ([#208]).
### Security
- RUSTSEC-YYYY-NNNN: describe the issue and link the advisory, or delete this heading.
[Unreleased]: https://github.com/OWNER/REPO/compare/v0.9.0...HEAD
[0.9.0]: https://github.com/OWNER/REPO/compare/v0.8.4...v0.9.0
[#208]: https://github.com/OWNER/REPO/pull/208
[#212]: https://github.com/OWNER/REPO/pull/212The crate, its types, versions and pull request numbers are placeholders. Replace them with what you actually shipped.
The short answer
- Keep CHANGELOG.md in the crate's repository and link it near the top of the README: crates.io renders the README on the crate page, and Cargo.toml has no changelog field.
- Below 1.0, Cargo counts a change in the left-most non-zero number as breaking. Going from 0.8.4 to 0.9.0 is a major upgrade for your users, so write it like one.
- Removing a public item or a Cargo feature is a major change; adding one is a minor change. Mark each break
**Breaking:**and give the replacement. - Say when the minimum supported Rust version goes up. Cargo's SemVer guide calls it possibly-breaking; clap and tokio raise it in minor releases and say so at the top of the entry.
- Run
cargo semver-checksbeforecargo publishso the version number and the changelog agree. - A broken release can't be deleted. Yank it with
cargo yankand add [YANKED] to its heading.
Free GitHub Action · no sign-up
Copy each CHANGELOG.md entry into the GitHub release
On every tag, the free LogPulse GitHub Action puts the matching CHANGELOG.md section into the GitHub release, breaking changes first. It reads v0.9.0 tags and, with changelog-path set to the crate's file, the my-crate-v0.9.0 tags cargo-release creates in a workspace. No account, and it never calls LogPulse.
name: Release notes
on:
release:
types: [published]
permissions:
contents: write
jobs:
notes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: kalmwerk/release-notes-action@v1
On GitHub now; Marketplace listing coming soon: releases. Rather keep a copy in your repository? Download 1.0.4 (29 KB). On GitLab? Use the CI/CD component
No CHANGELOG.md yet? See the notes your merged pull requests give first: generate release notes from GitHub, free and with nothing to install.
Free tool · no sign-up
Can a coding agent read your changelog?
Paste your repository, a GitHub release or a CHANGELOG.md link. The free converter shows every version, breaking change, migration step and deprecation it can extract, as JSON plus an llms.txt summary.
No AI, and your changelog isn't stored. Or paste a CHANGELOG.md instead
01Put the changelog where Rust users look
The Cargo manifest reference lists fields for a README, homepage, repository and documentation, but none for a changelog. crates.io renders the README on the crate's page, so that's where people start.
- Add a ‘Changelog’ link near the top of the README that points at CHANGELOG.md or your GitHub releases.
- Set
repositoryin Cargo.toml so people can get from crates.io to your code, and your changelog, in one click. - Use the same version in the changelog heading, the git tag and Cargo.toml, so readers and tools can match them up.
- In a workspace, keep one CHANGELOG.md per published crate, next to its Cargo.toml. tokio does this:
tokio/CHANGELOG.md,tokio-util/CHANGELOG.mdand so on. Monorepo changelogs covers the layout and the tags.
Want readers to see at a glance that the changelog is maintained? The free README changelog badge checks the CHANGELOG.md at the root of a public GitHub repository against Keep a Changelog and links to the report.
02Know which changes Cargo treats as breaking
Cargo applies Semantic Versioning with one twist for 0.x versions. Its SemVer guide says releases starting with “0.y.z” can treat changes in “y” as a major release and “z” as a minor release, and that “0.0.z” releases are always major changes, “because Cargo uses the convention that only changes in the left-most non-zero component are considered incompatible.” A dependency written as my-crate = "0.8" means >=0.8.0, <0.9.0, so cargo update never pulls in 0.9.0: your 0.9.0 entry is what people read when they decide to upgrade by hand.
| Change | Cargo's SemVer guide | Changelog line |
|---|---|---|
| Renaming, moving or removing a public item | Major | Breaking: Parser::parse_owned is removed. Use Parser::parse_str. |
| Adding a public item | Minor | Added Parser::parse_str. |
| Removing a Cargo feature | Major | Breaking: the legacy-api feature is removed. |
| Adding a Cargo feature | Minor | Added the simd feature (off by default). |
| Adding a private field to a struct whose fields are all public | Major | Breaking: Config can no longer be built with a struct literal. Use Config::default(). |
| Raising the minimum Rust version | Possibly-breaking | MSRV raised to 1.85. |
cargo-semver-checks describes itself as a tool to “lint your crate API changes for semver violations.” Run cargo semver-checks before publishing, or in CI with obi1kenobi/cargo-semver-checks-action@v2. Its own FAQ says it doesn't have lints for every kind of break yet, so still read the diff before you write the entry. More on choosing the number in semantic versioning and changelogs.
03Say when the MSRV goes up
The rust-version field in Cargo.toml records the minimum supported Rust version (MSRV). Cargo's SemVer guide lists changing it as possibly-breaking, and suggests documenting it with package.rust-version, “allowing Cargo’s dependency resolution to attempt to select older versions of your package when needed.”
Big crates bump the MSRV in minor releases and make it hard to miss. clap 4.6.0 has a ‘Compatibility’ heading whose only line is the MSRV update; tokio 1.54.0 says “The MSRV is increased to 1.85” right under the version heading. Do both: one line in the summary at the top of the entry, and one under Changed. If your policy is to bump the MSRV only in breaking releases, say so in the README.
04Deprecate in code first, then in the changelog
Rust has a built-in way to warn people before you remove something. rustc warns on every use of an item marked #[deprecated], and rustdoc shows the since version and the note on the item's page.
#[deprecated(since = "0.9.0", note = "use `Parser::parse_str` instead; removal in 0.10.0")]
pub fn parse_owned(&self, input: String) -> Result<Ast, Error> {
self.parse_str(&input)
}Then add a Deprecated line to the same release's changelog entry with the replacement and the version that will remove it, as in the template. A deprecation alone is a minor change; the removal is the breaking one. How to write deprecation notices has the wording.
05Yank a broken release, don't try to delete it
The Cargo Book is blunt about publishing: “a publish is generally permanent. The version can never be overwritten, and the code cannot be deleted.” What you can do is yank it. cargo yank removes the version from the index, but it “does not delete any data,” and Cargo “will not use a yanked version for any new project or checkout without a pre-existing lockfile.” Projects that already locked it keep building.
# Stop new projects from picking the broken version
cargo yank my-crate@0.8.3
# Changed your mind? Put it back
cargo yank --undo my-crate@0.8.3
# In CHANGELOG.md, keep the entry and mark it:
## [0.8.3] - YYYY-MM-DD [YANKED]Keep a Changelog uses the [YANKED] marker for exactly this. Add a line to the next entry saying what was wrong with the yanked version and that the new one fixes it, so people who locked 0.8.3 know whether to update.
06Automate the release with cargo-release, release-plz or git-cliff
Three tools do most of the work in the Rust ecosystem. They differ in who writes the entry: you, or your commit messages.
| Tool | What it does to CHANGELOG.md | Tags |
|---|---|---|
| cargo-release | Nothing by default. Its FAQ shows pre-release-replacements for a hand-written Keep a Changelog file, or git-cliff as a pre-release hook. | v0.9.0 at the repository root, my-crate-v0.9.0 for crates in a workspace |
| release-plz | Opens a release pull request with the version bump and a changelog written by git-cliff, “using the keep a changelog format by default”, and checks the API with cargo-semver-checks. | A tag for every released package |
| git-cliff | Writes the changelog from your commit history, best with Conventional Commits. | Reads your existing tags |
clap's CHANGELOG.md shows the cargo-release pattern for hand-written changelogs: an <!-- next-header --> comment above ## [Unreleased] - ReleaseDate, which cargo-release rewrites into the new version and date on release.
pre-release-replacements = [
{file="CHANGELOG.md", search="Unreleased", replace="{{version}}"},
{file="CHANGELOG.md", search="ReleaseDate", replace="{{date}}"},
{file="CHANGELOG.md", search="<!-- next-header -->", replace="<!-- next-header -->\n\n## [Unreleased] - ReleaseDate", exactly=1},
]For how these tools compare with release-please, semantic-release and Changesets, see semantic-release vs release-please vs Changesets.
07Common mistakes in crate changelogs
These are the ones that cost users an afternoon.
- Treating 0.8 → 0.9 as a minor release. Below 1.0 it's the breaking one. ‘Refactored the API’ isn't an entry; list each break and its replacement.
- Removing a Cargo feature quietly. Projects that still enable it stop resolving. Mark it breaking and say what replaces it.
- Raising the MSRV without a line. Users on an older toolchain get a build error and nothing in the changelog explains it.
- Deleting the entry for a yanked version. Keep it, mark it [YANKED], and say in the next entry what was wrong.
- A tag, Cargo.toml and a heading that disagree. Tools that copy notes into releases look the version up from the tag, so
v0.9.0,version = "0.9.0"and## [0.9.0]must match. - Only a link to the commit log. A compare link is a good footer, not a substitute for the entry.
08Generate the entry from your commits
Whichever way you release, you can draft the entry from git in a minute and spend your time on the part only you can write: what users must change.
- Run
git log v0.8.4..HEAD --no-merges(use your last tag) and paste the output into the free changelog from commits tool. It sorts the commits into Added, Changed, Fixed and the rest, and flagsfeat!:commits andBREAKING CHANGE:footers as breaking. - Crate on GitHub? The GitHub release notes generator does the same from two releases or tags, without cloning.
- Edit the draft: merge related commits into one line, add the replacement to every
**Breaking:**entry, add the MSRV line, and paste it under the new version in CHANGELOG.md. - Check it with the free changelog validator, then let the GitHub Action copy the section into the GitHub release when you push the tag.
# Everything since the last release, with commit bodies for BREAKING CHANGE: footers
git log v0.8.4..HEAD --no-merges
# Workspace crate: only the commits that touched it
git log my-crate-v0.8.4..HEAD --no-merges -- my-crate/Real projects that do this well
Public release notes worth copying from. Each link opens the project's own page.
- clap Keep a Changelog-style headings with the area a change touches, such as (derive) or (help), in italics before the line, a ‘Compatibility’ heading for MSRV bumps, and a 5.0.0 section that lists breaking changes ahead of the release.
- tokio One changelog per crate in the workspace. Each line starts with the module it touches (fs:, net:, runtime:), and MSRV increases are stated right under the version heading.
- rand Keep a Changelog for a 0.x crate, with links at the top to a separate rand_core changelog and to an upgrade guide, and a one-line warning at the top of a release that fixes a soundness bug.
- ripgrep A command-line tool's changelog: a short paragraph on what the release is about, then platform support, performance, features and bug fixes, with feature and bug lines linked to their issue or pull request.
Before and after
Too vague
0.9.0: refactored the parser API, cleaned up features.
Specific and actionable
0.9.0 (breaking): Parser::new() now takes a Config; use Parser::new(Config::default()). The legacy-api feature is removed; call Parser::parse_str instead. MSRV is now 1.85.
Fictional example: use your own verified names, versions and behavior.
LogPulse
Generate release notes with LogPulse
LogPulse is a hosted changelog that people and coding agents can both read. Here's exactly what it can do for the steps above, and what it can't.
Check your changelog, free
Paste a CHANGELOG.md or a GitHub releases link. A deterministic parser (no AI; your changelog isn't stored) shows the versions, breaking changes, migration steps and deprecations an agent can extract.
Draft notes from GitHub
Connect a repository: merged pull requests, commits to your default branch and published GitHub releases collect in an inbox. AI drafts a note in the tone you pick, listing breaking changes and deprecations only when the changes clearly show them. Nothing is published until you approve it. 3 AI drafts on Free; unlimited on Open source and Pro. Pro opens soon: .
Publish once, read everywhere
Approved notes go to a hosted changelog and an in-app widget, to email subscribers on Open source and Pro (Pro opens soon), and to a JSON feed and MCP server coding agents can query. CI and agents can publish with an API key.
What it doesn't do: LogPulse doesn't tag releases, bump versions, publish to npm or PyPI, or write CHANGELOG.md back to your repository; keep your release tooling for those. AI drafts can miss context, so review them like a pull request.
Before you publish
- The README links to the changelog and Cargo.toml sets repository
- The changelog heading, git tag and Cargo.toml version match
- Every breaking change, including removed Cargo features, is marked and has a replacement
- An MSRV increase is in the summary and under Changed
- cargo semver-checks passes, or its findings are in the changelog
- Deprecated items carry #[deprecated] with since and note
- Yanked versions are marked [YANKED]
Common questions
Does crates.io show my changelog?
No. crates.io renders the README you set with the readme field, and Cargo.toml has no changelog field. Link CHANGELOG.md, or your GitHub releases, from the top of the README.
Is raising the MSRV a breaking change?
Cargo's SemVer guide calls it possibly-breaking: some projects treat it as major, others as minor. Many large crates, including clap and tokio, raise it in minor releases and announce it at the top of the entry. Pick a policy, put it in the README, and always list the change.
Can I delete a version I published by mistake?
No. The Cargo Book says the code of a published version can't be deleted and the version can't be overwritten. Yank it with cargo yank so new projects don't pick it, publish a fixed version, and mark the yanked entry [YANKED] in CHANGELOG.md.
Sources
Facts last checked against these sources on .
- Keep a Changelog 2.0.0
- The Cargo Book: SemVer compatibility
- The Cargo Book: specifying dependencies
- The Cargo Book: the manifest format
- The Cargo Book: cargo yank
- The Cargo Book: publishing on crates.io
- The Rust Reference: the deprecated attribute
- cargo-semver-checks
- cargo-release FAQ: maintaining a changelog
- release-plz
- git-cliff
Next step
Automate this on every release
Skip the copy-paste next time: let your pipeline write the release notes when you tag. Free, no LogPulse account.
- GitHub ActionWrites each GitHub release from CHANGELOG.md or the pull requests merged since the last tag.Set it up
- GitLab componentThe same notes for GitLab releases, in a tag pipeline. Only needs CI_JOB_TOKEN.Set it up
- Free API & MCPRelease notes, changelog checks and conversion over HTTP or MCP. No key, no account.Read the docs
- A draft from every merged pull request, published to your widget, hosted changelog and subscribers' inboxes.€12/month or €99/year + VAT · opens soonJoin the waitlist
Read next
How to write release notes for open-source libraries
Copy-paste release notes template for open-source libraries, 4 annotated examples modelled on Node.js, Django, Python and Vite, and a free generator.
Read the guide Breaking changes, deprecations and versioningSemantic versioning cheat sheet for changelogs
Which change needs a major, minor or patch bump? A cheat sheet of 12 common changes with the changelog line for each, plus 0.x and prerelease rules.
Read the guide Open-source libraries and packagesHow to keep a changelog in a monorepo
One changelog or one per package? A copy-paste per-package CHANGELOG.md, tag formats for Changesets, Nx and release-please, and 4 real monorepo examples.
Read the guide Open-source libraries and packagesHow to keep a changelog for an npm package
Where npm users look for changes, how to keep versions, git tags and headings in sync, ship prereleases without moving latest, and deprecate old versions.
Read the guide Open-source libraries and packagesHow to keep a changelog for a Python package on PyPI
Link a changelog from pyproject.toml, version with PEP 440, ship pre-releases pip skips, yank instead of delete, warn before removals, automate with towncrier.
Read the guideMore guides: open-source libraries and packages
- Changelog vs release notes: what's the difference?
- CHANGELOG.md format, explained line by line
- Release notes templates in Markdown
- Keep a Changelog vs GitHub Releases
- How to generate a changelog from git commits
- How to write release notes from commits (Conventional Commits)
- semantic-release vs release-please vs Changesets (and git-cliff)
- How to write GitLab release notes and keep a changelog
Tools and resources
- Free tool: changelog from git commits
- Free README changelog badge for your crate's repository
- Free tool: Keep a Changelog validator
- How to write deprecation notices
- Free tool: convert a CHANGELOG.md or GitHub release to JSON
- Free tool: GitHub release notes generator for any two releases
- Free GitHub Action: release notes from your CHANGELOG.md on every tag
- kalmwerk/release-notes-action on GitHub: the Action's code and releases
- Free tool: a GitHub repo's changes since its last tag, as a changelog
- LogPulse developer docs: feed, API and MCP server
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.