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)';
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?
Top comments (9)
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.
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:
1.0.0.142
1.0.1.156
1.1.0.205
1.2.0.432
1.1.1.446
1.2.1.447
Along the way there were builds like 1.0.0.138, 1.0.0.139, 1.0.0.140 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 1.0.0.140 (which had that one tiny mistake) and the actual release version of 1.0.0.141. There's literally never a conversation that involves a question like "is this the actual 1.0.0??"
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.
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.
And defines the common terminology: major, minor and patch (not masterversion, version and subversion).
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.
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.
Apps can have "incompatible changes" also: e.g., if the app safe something on file and change format, or drop support to some hardware.
semver.org outlines common practice on how to do versioning