DEV Community

WhatShipped
WhatShipped

Posted on

Write commit messages your future self will thank you for

#opensource #productivity #git #devtools

You know the feeling. You open git log three weeks after a sprint and see:

fix
wip
ok
asdf
finally
please work
Enter fullscreen mode Exit fullscreen mode

You have no idea what you were doing. Your changelog is going to be a nightmare. Your coworker's PR review is going to take twice as long.

This is the commit message problem — and the fix is simpler than you think.

Why commit messages matter more than you think

A commit message isn't just a label. It's a unit of communication that travels:

  • Into your git log and git blame
  • Into PR descriptions and code reviews
  • Into your changelog and release notes
  • Into your team's understanding of why something exists

When commit messages are bad, everything downstream gets harder. When they're good, a lot of things become almost automatic.

The format that works

The simplest improvement you can make is adopting a consistent structure:

<type>: <what changed, in plain English>
Enter fullscreen mode Exit fullscreen mode

Where type is one of:

  • feat — new feature
  • fix — bug fix
  • docs — documentation only
  • refactor — no behavior change, just restructuring
  • chore — maintenance, dependency updates
  • breaking — something that changes existing API or behavior

Real examples:

feat: add CSV export to dashboard
fix: prevent session expiring early on mobile browsers
refactor: extract auth logic into useAuth hook
chore: upgrade eslint to fix security warning
breaking: rename config.apiKey to config.key
Enter fullscreen mode Exit fullscreen mode

These are searchable, parseable, and readable six months later.

The three questions to ask before committing

Before you type the message, ask yourself:

  1. What does this change for the user? Not for you — for them.
  2. Would a teammate understand this without context?
  3. Could this become a changelog line as-is?

If the answer to all three is yes, you have a good commit message. If not, rewrite until it is.

Conventional Commits is worth the 10 minutes

Conventional Commits is a lightweight spec built around the format above. The benefit of adopting a standard (rather than your own variation) is tooling.

Semantic versioning tools can bump your version automatically. Changelog generators can group and format entries. CI pipelines can validate messages before merge.

The spec is simple enough to internalize in one reading. The compounding benefit is significant.

The compound effect

Good commits → readable git log → fast PR reviews → easier changelogs → better release notes → users who understand what changed between versions.

It all starts at the commit message. The earlier in a project you adopt this, the more you get back.

What to do if your history is already a mess

Don't backfill. It's not worth the time.

Just start with the next commit. One good message today is worth more than a weekend of rewriting old ones.

If you need to generate a changelog from a messy history right now — for a release that's going out this week — tools can help. WhatShipped reads your git history and uses AI to produce a readable changelog even when the commits are rough. There's 1 free generation to try it.

The habit

The goal isn't perfection. It's consistency.

Pick the format. Apply it to the next commit. Then the next. After a week it's automatic, and your future self — and your users — will notice.

Top comments (0)