DEV Community


When is it right to change the version number of a project?

I'm the ghost of Developers Past...
・1 min read

For the sake of sanity:

let versionstring = '1.2.3';
let masterversion = 'the first digit of the version string (e.g. 1)';
let version = 'the second digit of the version string (e.g. 2)';
let subversion = 'the third digit of the version string (e.g. 3)';
Enter fullscreen mode Exit fullscreen mode

As someone who's only very recently written a codebase that's actually useful (and works!), I'm yet to understand half a million things about versioning, contributing and licenses, but the most pressing question I've had for the past week is:

  • When is the right time to bump the masterversion/version/subversion of a web app?

Do you bump the subversion up when you've fixed a bug? If you've made a huge change, is it okay to bump the subversion more than one notch? When is it the right time to change the version or the masterversion?

What do you do for your projects? And how often do you change the masterversion/version/subversion? Do you put out changelogs for every version, or just major bumps?

If you put out changelogs, how do you do it if it's a private repository?

Discussion (10)

belinde profile image
Franco Traversaro

The first number, in my opinion, changes when a backward incompatible change happens. The second, when you introduce new features. The third, when you're just fixing a bug.

groogs profile image
Greg MacLellan

This is a pretty non-technical-user-friendly scheme. The first number may also change for marketing reasons, eg: make a big splash about a really major new feature (or often, a new feature that replaces an older feature).

I also like to have a 4th number on the end which is just a build number, incremented every build by your CI system. You might end up with versions looking like:

Along the way there were builds like,, but those were not final, and never saw the light of day outside dev/QA.

Using that it's trivially easy to see the difference between (which had that one tiny mistake) and the actual release version of There's literally never a conversation that involves a question like "is this the actual 1.0.0??"

ghost profile image
Ghost Author

That's a really good way of thinking about it, I feel. I might give that a test run for a while, and see see how it goes.

dmerand profile image
Donald Merand

When in doubt, semantic versioning is a good place to start. Personally I prefer change logs for every change, but at a minimum you need to point out breaking changes.

mikeralphson profile image
Mike Ralphson

And defines the common terminology: major, minor and patch (not masterversion, version and subversion).

erikpischel profile image
Erik Pischel

Semantic versioning is for APIs. For an app (mobile, web or desktop), what is an "incompatible change"?

"Subversion" is for any patch (bugfix) release. You have to decide whether a regular release increases masterversion and resets version or just increases version.

groogs profile image
Greg MacLellan

Arguably, overhauling/rewriting a major feature or major chunk of UI. Sometimes you intentionally drop features, sometimes you inadvertently do. There's no better way of finding all the bizarre ways users have come up with to use features (or bugs) in ways you never intended.

One of my favorites was a "note" feature, which had fields for Title, Date, User, and half-dozen other things. Literally nothing in our software used any of them, it was just displayed on a screen, and from what we could tell, only a handful of users used the feature and didn't use all the fields. We were rebuilding a major part of the system and the changes meant that the notes UI and database schema had to be reimplemented, so we simplified it to be just a single textarea input.

Turns out we broke an ordering system for one of our major customers -- they were using the Title field for entering order number, and one of the other fields ('Service Requested By' or something like that) for a shipment tracking number, and had a bunch of custom SQL they ran to extract these values, then update the status back from their ordering system.

In this case it was a "major" version bump, so they were doing extra testing and found this problem before upgrading.

belinde profile image
Franco Traversaro

Apps can have "incompatible changes" also: e.g., if the app safe something on file and change format, or drop support to some hardware.

brok3nkeys profile image
Mark Griffiths outlines common practice on how to do versioning