Don't Panic — Release Notes and Changelogs

A changelog is the ongoing, curated list of what actually mattered between versions. Release notes are the announcement you hand someone on release day. Same raw material, different jobs. If you only remember one corridor sentence from this course, make it that split.

Before these habits spread, people pointed at git history and called it communication. Git is excellent archaeology. It is a lousy customer newsletter. Commits talk to developers about a unit of work. Changelog entries talk to upgraders about behavior. Mixing them up is how typos get equal billing with breaking API changes, which is how readers learn to ignore you.

Hang the practice on three ideas. First, keep a repository file (usually CHANGELOG.md) as the canonical record: Unreleased at the top, versions with ISO dates, newest first, grouped under Added, Changed, Deprecated, Removed, Fixed, and Security. Second, let the versioning scheme do signaling work (SemVer's major/minor/patch, or CalVer when the calendar is the point) while the prose still names what broke. Third, treat automation as a draft machine: Conventional Commits, labeled PRs, Changesets, release-please, semantic-release, git-cliff. Useful. Not the final editor.

The surprise for many teams is where the work actually lives. Formatting the Markdown is the easy afternoon. Notability is the hard evening. Generators cheerfully assume every commit deserves a bullet and that one commit equals one entry. Multi-commit features and quiet breaks both escape that fantasy. Keep a Changelog's updated advice is almost rude in its clarity: machines can draft, humans curate. Also, do not make CI demand a changelog edit on every pull request unless you enjoy a museum of "wip" lines.

Deprecate before you remove. Mark breaks in place. List yanked releases instead of pretending they never happened. Prefer a file that travels with the repo over notes that only exist in a host database.

Where next: the Intro and Cheatsheet for structure and type rules; Practice and the Exercise when you want to curate a noisy branch into a real section; Field Notes when you need the judgment calls teams regret; Landscape and Reference when you are picking tools. Don't Panic is the map. The other tabs are the terrain.