How to write release notes for open-source libraries
Give downstream maintainers an auditable path between package versions.
01Anchor entries to published artifacts
Match the heading to the registry version and release tag. Include the date and a comparison link when available. Avoid treating an unreleased branch as an installable version.
02Describe compatibility as a matrix
State minimum runtime, framework and peer-dependency versions. A new Node requirement can block adoption even when the exported API looks unchanged. Test supported combinations in CI rather than inferring support.
03Credit contributors without replacing the explanation
Link pull requests and thank authors, but describe the user-visible change in the entry itself. A PR title such as refactor parser is not a migration instruction for downstream users.
04Keep upgrade instructions independently usable
Include old and new import paths, configuration keys and expected behavior. Publish the same version and migration facts in a structured feed so an agent need not guess from commits. Verified public OSS repositories can apply for LogPulse’s Open source plan.
Before and after
Too vague
Cleanup in #412.
Specific and actionable
2.0.0 requires Node 20+. Replace import {parse} from "@acme/parser/legacy" with import {parse} from "@acme/parser". parse now throws ParseError for invalid input; catch it at your input boundary.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Match registry version and tag
- Check runtime and peer dependencies
- Link relevant pull requests
- Test the documented migration from the previous major
Common questions
Keep reading
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.