Changelog That Matches the Git Tag

The tag is v0.3.0, and CHANGELOG still ends at last month’s guess. You just ran git tag to mark the release you deployed to production 10 minutes ago, but you’re staring at a 4-week-old changelog entry for v0.2.9 that doesn’t mention any of the 17 commits you merged since then. Skipping this sync step now means you’ll spend 2 hours next quarter digging through git history when a user reports a bug tied to the v0.3.0 deploy, so it’s worth fixing before you step away from your desk. The tag-to-changelog pairing card below gives you a reusable, fill-in-the-blank structure to confirm every tag you push has a 1:1 matching entry in your changelog before you announce the release.

Tag name you type before writing the entry

The number one cause of mismatched tags and changelogs is writing the changelog entry first, then adjusting the tag name last minute to fix a semver error, and forgetting to update the changelog. You always type the tag into your terminal first, with the exact semver value you confirmed based on the changes you’re shipping. For v0.3.0, that means you run `git tag -a v0.3.0 -m “Release v0.3.0: Add user profile export”` before you open your CHANGELOG.md file. This locks the tag value in your git history first, so you don’t accidentally write the wrong version number in the changelog. Illustrative example: If you realize after tagging that you missed a breaking change that should bump the minor version to v0.4.0, you delete the existing tag with `git tag -d v0.3.0`, create the correct v0.4.0 tag, then write the changelog entry for v0.4.0, not the other way around. This workflow eliminates 90% of common mismatches for solo maintainers, as it removes the risk of last-minute tag changes going unrecorded in your changelog.

One-line change a later checkout can trust

After the tag is locked, the first line of your changelog entry for that tag must be a single, specific sentence that anyone checking out that tag 6 months from now can use to confirm they’re looking at the right codebase state. For v0.3.0, that line would be: “Adds CSV and JSON export functionality for all user profile data, including saved project lists and preference settings.” No vague phrases like “various improvements” or “bug fixes” allowed here, because those don’t give future you or any contributor a concrete way to verify the tag matches the changelog. If you check out v0.3.0, you can test the export feature immediately to confirm the code matches what the changelog says it does. This line should never be longer than 120 characters, so it’s scannable in a 1-page view of the full changelog. You can also copy this line directly into your git tag message, so the tag itself includes the same summary as the changelog for extra cross-reference.

Breaking note you never bury in a paragraph

If your release includes any breaking changes, you add a separate, all-caps line immediately after the one-line change summary, marked with a `BREAKING CHANGE:` prefix, so it’s impossible to miss. For v0.3.0, the breaking note might be: “BREAKING CHANGE: The GET /api/users/profile endpoint now returns a 401 status code for unauthenticated requests, instead of a partial public profile payload.” You never tuck this information in the middle of a bullet list of bug fixes, because a developer upgrading their dependency might skip over that list and miss the breaking change, leading to production outages. Even if the breaking change is small, like updating a default config value that only affects self-hosted users, it gets its own dedicated line directly under the one-line summary. For solo projects, you can add a rule that any changelog entry with a breaking change must have a ⚠️ emoji warning next to the tag header, so it stands out even when scrolling quickly through hundreds of entries.

Typo-only commits that do not get a version bump

When compiling the list of changes for the changelog, you explicitly exclude any commits that only fix typos, update documentation wording, or adjust whitespace in code files. These changes do not affect functionality, so they don’t warrant a version bump, and they don’t belong in the public changelog entry. For v0.3.0, you might have 3 commits that fix typos in the export feature’s help text, but those don’t get listed in the changelog. If you only have typo fixes to deploy, you don’t create a new git tag at all, you just push the changes directly to production without a new changelog entry. This keeps your changelog focused on user-facing or developer-facing functional changes, so users don’t have to sift through dozens of trivial entries to find the updates that matter to them. Example measurement: For a small project with 1-2 deployments a week, excluding typo commits reduces changelog bloat by 30% on average, making it far easier to track meaningful changes over time.

File location you link from the README

Finally, you need to store your CHANGELOG.md file in the root of your repository, and link directly to it from the first section of your README.md file, so anyone visiting your repository can find it immediately. You never store the changelog in a nested docs folder or on a separate external page without a direct link from the root README, because that makes it hard for users and contributors to cross-reference tags with changelog entries. For your v0.3.0 release, after you write the changelog entry, you add a line to your README that says “View the full changelog for all releases: [CHANGELOG.md](./CHANGELOG.md)” directly under the project description. You can also add a link to the specific tag’s entry in your release notes on GitHub or GitLab, so users who find the release via your repository’s release page can jump directly to the matching changelog entry. If you host a public documentation site for your project, embed the changelog directly on a dedicated page, and link each entry to the corresponding git tag in your public repository for extra transparency.

Right now, open your most recent project’s CHANGELOG.md file, cross-check the last tag you pushed against the latest changelog entry, and fill out the first row of the tag-to-changelog pairing card for that release to confirm they match before you move on to your next task.