Semantic versioning

[MoritzLost]

It was announced that starting with version 4, Craft would switch to an annual release cycle:

These will kick off our new annual release cycle for major versions. Each major version will come with two years of full support, and one more year for critical security fixes.

I assumed this would mean a switch to semantic versioning as well, following the generally accepted standard:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes

However, now the latest releases of Craft were 4.2.0.1 and 4.2.0.2 instead of 4.2.1 and 4.2.2. I wanted to ask what the difference is between a release with a new patch number (3rd digit) and a release with an added fourth digit? What is the difference for me as a developer and user in practice?

Based on the changelog, it looks like the difference is that releases with a bump in the patch number include changes in the Added / Changed / Deprecated categories, while releases with a fourth digit include only bugfixes in the Fixed category. In this case, what is the difference between a minor version bump and a patch version bump – so what is the difference between an increase in the second and third digit? Judging by the changelog, the only difference is the amount of changes in this release, which isn't really a useful metric.

My suggestion would be to follow semver more closely and use a minor version increase for every release that adds any features. This way, patch versions (3rd digit) can be reserved for bugfix releases and there's no need for a fourth digit. As a developer, those three levels of granularity are all I need to make a decision on when and how to update, and the occasional fourth digit just makes things more confusing.

If there is indeed a reason for the fourth digit I would be interested in hearing it. In this case, I think it would also be a good idea to provide some documentation on the versioning scheme that is used, as I can't find this information anywhere.

[mmikkel]

You're right that the fourth version digit is kind of ambiguous. FWIW, I've mostly seen it as a signal for quick regression bug fixes on the tail-end of a bigger release (major, minor or patch).

The thing is that with an application like Craft, the line between a bug fix and a change in behaviour can often be extremely thin, or even impossible to completely separate, due to the fact that Craft is such a complex and extensible piece of software.

If Craft followed semver to the letter (i.e. by ditching the fourth digit and only allowing completely unambiguous bug fixes in its third digit patch releases) what would likely happen is that its current use of second and third digit versions would become conflated. In other words, most releases would probably become 2nd digit, "minor" releases, which means that developers would lose the very useful distinction between intentional changes and new features – which are supposed to be backwards compatible, but still on a scope where a glance at the changelog is warranted – and the "more minor" patch releases, which are typically quite safe to install.

Personally, I appreciate the new release schedule (particularly, the fact that the minor releases are actually minor, i.e. most likely without breaking changes, and the long-term support for previous major versions). I also think it's great that the team seems to strive for a closer adherence to the semver spec. But, I don't think that following semver religiously would necessarily be more helpful to Craft developers than how the versioning is currently being handled, since 4.0.

[MoritzLost]

@mmikkel Thanks for the thorough reply! I understand the intent better now, and I agree that reserving the minor version number for more impactful changes is helpful. In this case though, I'd say what should be merged are the patch number and the fourth digit. Following your example, both the third and fourth digit signal that nothing super noteworthy happens, so I can just install those updates safely. So from a user and developer perspective, there's really no difference between 4.2.0.1 and 4.2.1, so there's no need for the fourth digit. This change in versioning would adhere to semver and maintain the useful distinction you mentioned. Or am I missing something?

[mmikkel]

Yeah, I don't actually know the real intent behind the fourth digit and I agree that it is a bit unclear (vs. the third digit). Again, I've mostly seen it as a signal for timely regression fixes after a bigger release dropped, which I think is useful (vs. bigger "patch" version numbers). But, if nothing else it would be great to get some official clarification on this :)

[brandonkelly]

We are following semver as closely as possible without being impractical. (Even the most innocent-seeming changes sometime lead to unintended breaks, e.g. we add a new property and it turns out someone was extending the same class and had already added that same property, but with a slightly different signature.)

In general we’re going with:

• Major – annual(-ish) breaking change release with major new features and changes in behavior.
• Minor – slight changes in behavior, non-breaking new features, notable DX improvements like new events, etc.
• Patch – primarily bug fixes/behavioral corrections, and whatever API changes were required to acheive them.
• Hotfix – fixes to critical regressions caused by the previous major/minor/patch release, so long as the fixes can be made without any broader code impact.

You could say hotfixes are the -FINAL-2.psd of software versioning.

[MoritzLost]

@brandonkelly Thanks for the clarification! In this case, maybe this information should be added to the docs so it's easy to find? Would fit nicely on the Updating Instructions page, right?