Blog / Build with AI /

Version numbers and changelogs for small tools

Your small tool is on version 1.0. Then you fix a typo and call it 1.1. A month later, a bigger change becomes 1.1.1, because why not. Six months on, nobody including you can say what changed between them.

Version numbers and a changelog are the cheapest bits of professionalism you can add to a project. They take minutes to set up, and they help in places you wouldn’t expect: support emails, store reviews, rollbacks and your own memory.

What a version number is for

A version number answers one question: is what I have the same as what you have? When a user says “it broke after the update”, you need to know which update.

For a personal project it also tells you if a bug existed before or after a change. For something other people install, like a browser extension or a WordPress plugin, store listings usually require a version and rely on it to deliver updates.

The three-part system

The most common scheme is called semantic versioning. It uses three numbers: MAJOR.MINOR.PATCH, for example 2.4.1.

  • PATCH goes up for small fixes that don’t change what the tool does. 2.4.1 becomes 2.4.2.
  • MINOR goes up when you add something new that doesn’t break existing use. 2.4.2 becomes 2.5.0 (the patch resets to zero).
  • MAJOR goes up when you change something in a way that could break what people already rely on. 2.5.0 becomes 3.0.0.

An easy way to remember: patch is fix, minor is feature, major is “you may need to do something”.

Examples for small tools

What you did New version (from 1.4.2)
Fixed a typo in a button 1.4.3
Fixed an export bug 1.4.3
Added a dark mode 1.5.0
Added a new setting 1.5.0
Changed how saved data is stored, so old data needs migrating 2.0.0
Removed a feature people used 2.0.0

If you’re unsure, ask: “Could this change cause a problem for someone who simply updates?” If yes, think about a bigger bump.

Starting out

Many people begin at 0.1.0 while the tool is still rough, then call it 1.0.0 when they’re comfortable with people depending on it. That’s perfectly fine. Version 0.x quietly says “this may still change a lot”.

Don’t agonise. A consistent, imperfect scheme beats a clever, inconsistent one.

Browser extensions have rules

If you build a Chrome extension, the version lives in manifest.json and must be numbers separated by dots, such as 1.2.0. The store compares it with the previous version, and each upload must be higher than the last published one. Letters like “1.2-beta” aren’t accepted in that field. Updating an extension without breaking users covers what to do around releases.

WordPress plugins and themes use a version in their header comment. The same idea applies, and update checks compare versions to decide whether to show “update available”.

The changelog: version numbers with stories

A number alone says little. A changelog says what each one contained. Here’s a format that’s easy to keep:

# Changelog

## 1.5.0 - 2024-07-30
### Added
- Dark mode, following the system setting

### Fixed
- Export no longer fails when a name contains a comma

## 1.4.3 - 2024-07-12
### Fixed
- Typo on the welcome screen

Rules that make it useful:

  • Newest first.
  • Dates with each version, in an unambiguous format such as 2024-07-30.
  • Group changes under Added, Changed, Fixed and Removed.
  • Write for users, not developers. “Export no longer fails when a name contains a comma” beats “fixed CSV regex”.
  • Mention anything that needs action, like re-entering a setting.

Where to keep it

A plain CHANGELOG.md file in your project is fine. Show the latest changes in your tool’s store description or on a small “What’s new” section. If you use Git, tag each release with its version number so you can find the exact code later.

If your notes are messy, you can ask AI to tidy them, but give it explicit rules: “Use only the changes I list. Do not add any other items.” Otherwise it may helpfully invent improvements. I explore a small tool for this in building a release notes formatter with AI.

When to release

Small and often beats large and rare. Each release should contain a handful of related changes, so if something goes wrong you know where to look. Avoid releasing in a rush at the end of the day, or just before you disappear for the weekend.

Before each release, a short routine helps:

  1. Update the version number in one place (ideally just one).
  2. Write the changelog entry.
  3. Test the main paths.
  4. Save or tag the code.
  5. Publish.

Pre-release labels, if you need them

Sometimes you want people to try something before it’s final. Semantic versioning allows a suffix such as 2.0.0-beta.1, which sorts before 2.0.0. That’s fine in your own files, in Git tags and on a download page. Just remember the earlier point: some stores accept only plain numbers in the version field, so keep the label in the listing text and release notes, not in the number.

Common mistakes

  • Forgetting to bump. The store rejects the upload, or users don’t get the update.
  • Bumping everything as “major”. It scares people for no reason.
  • Changing things without changing the number. The worst one, because nobody can tell which copy is which.
  • Version numbers that differ between files. Keep one source of truth.
  • No changelog until someone asks.

Key takeaways

  • Use MAJOR.MINOR.PATCH: fix, feature, “you may need to act”.
  • Start at 0.1.0 if you’re still experimenting.
  • Keep a dated, newest-first changelog written for users.
  • Bump the number every time anything ships.

What would your last three updates have been called, and could a user have told them apart?