Guides / Changelog

How to turn your Git commits into a clean changelog

A practical guide for indie developers · ~7 min read

Your commit history is an honest record of how the work happened: wip, fix, asdf, actually fix it this time. A changelog is the opposite — a curated story of what changed for the person using your project. This guide shows you how to get from one to the other without it becoming a chore.

Why a changelog is worth the effort

For a side project, a changelog does three quiet but valuable things. It tells visitors the project is alive — nothing kills trust faster than a page that looks abandoned. It gives returning users a reason to come back ("oh, they shipped the thing I asked for"). And it gives you a public trail of momentum you can point to when you launch, apply somewhere, or just need proof to yourself that you're moving.

The trick is that a changelog is for readers, not for Git. A good entry answers "what does this mean for me?" — not "which files did you touch?"

The format that works: Keep a Changelog

You don't need to invent anything. The widely-used Keep a Changelog convention groups entries under a version and a date, then sorts them into a small set of categories:

## [1.4.0] — 2026-06-02
### Added
- Email digest so you can follow a project without an account.

### Fixed
- Login no longer hangs on Safari iOS.

### Changed
- Faster project page load on slow connections.

The four categories you'll use most: Added (new features), Fixed (bug fixes), Changed (behavior or improvements), and a catch-all like Other for housekeeping. That's enough structure to be scannable and not so much that you stall deciding where something goes.

Step 1 — Pull the commits since your last release

The raw material is one command. To list everything since your last tag:

git log v1.3.0..HEAD --oneline

Or, if you don't tag releases, just grab the last couple of weeks:

git log --since="2 weeks ago" --pretty=format:"%h %s"

You'll get a list like a1b2c3 wip, d4e5f6 fix the thing, 9z8y7x add subscribe button. This is your draft — most of it isn't usable as-is, and that's fine.

Step 2 — Throw away what readers don't care about

Be ruthless. Delete merge commits, formatting-only changes, dependency bumps nobody asked about, and anything labeled wip, test, oops, or refactor that has no user-visible effect. A changelog with five real lines beats one with forty noisy ones. If a commit didn't change anything a user can see or feel, it usually doesn't belong.

Step 3 — Rewrite the survivors in plain language

This is the actual work, and it's where most changelogs die. Each surviving commit becomes a sentence written from the reader's point of view. A few before/after examples:

fix → Fixed a crash when opening the dashboard with no projects.
add gh oauth → Added: connect GitHub to import your commits automatically.
perf → Project pages now load noticeably faster on mobile.

Two rules carry most of the weight: lead with the user benefit, and avoid internal jargon (function names, ticket numbers, file paths). If you can't explain what a commit did for the user, that's a strong signal it should be cut, not rewritten.

The shortcut for next time: conventional commits

If rewriting after the fact feels like tax, fix it at the source. Conventional commits ask you to prefix each message with its type:

feat: add email subscribe button
fix: resolve Safari iOS login hang
perf: lazy-load project page images
chore: bump dependencies

Now your changelog almost writes itself: feat: commits become "Added", fix: become "Fixed", perf: become "Changed", and chore: gets dropped. Tools like git-cliff, release-please, and standard-version can generate a CHANGELOG.md straight from these prefixes. The catch is discipline — it only works if you actually write commits that way, every time.

Where the changelog should live

A CHANGELOG.md in your repo is good for other developers, but most of your users will never open GitHub. If the changelog is meant to build trust with visitors, it needs to live somewhere they already are: on your project's public page, where a casual visitor can see "shipped 3 days ago" without cloning anything.

Skip the rewriting step

Viestro reads your repo, flags weak messages like wip and fix, suggests clean rewrites, and publishes the ones you approve to your project's public page — drafts stay private until you say so. You stay in control; it just removes the busywork.

Try it free →

A changelog isn't documentation you owe anyone. It's a small, repeated signal that your project is going somewhere — and those signals compound. Start with the last two weeks, write five honest lines, and publish them where people can see.