Understanding Magento2 Versioning Specification

Introduction

The Magento version specification is quite complex. One need only read the release notes. Take the example of 2.3.0 and 2.3.1. A big release and another big release is my interpretation. You can spend a whole day reading them and trying to understand the difference. One may interpret that 2.3.0 brings about a lot of changes in terms of the way the system is run and in 2.3.1 a lot of improvements on it. There are further complications which I tackle later in this post.

Or maybe join me in my deep dive into understanding their versioning system by analysing the potential backwards compatibility breaks they introduce when upgrading your Magento instance.

Versioning Specification

Magento2 uses their own versioning specification, which may be interpreted as:
X - Different Application
Y - Major backward compatibility break extremely likely
Z - Major backward compatibility break possible
p - Patch Version where minor backward compatibility break is possible, but unlikely

For example 2.3.7-p2 may be interpreted as Magento2 version 3.7 with security patch version 2.

More info: https://devdocs.magento.com/guides/v2.3/release-notes/backward-incompatible-changes/reference.html

This differs from semver which is interpreted as:
X - Major version: Major backward compatibility break
Y - Minor version: No backward compatibility break
Z - Patch Version: No backward compatibility break.

More Info: https://semver.org/

Backward compatibility

Backward compatibility breaks means that something was changed to the effect that it can break functionality. A major one means major components stop working to the extent that the website fails to load (P0), because its no longer compatible with a service, or add to cart is not working (P1), because certain features now require enforcement like catalog permissions and so on. This may include some P2 issues. A minor one would break visual or functional website functionality (P3), but still allows the basic functions of the website to continue. This may also include P2 issues.

The relevance of Backward compatibility breaks are that you may have services installed that are no longer supported, code changes such as classes/methods or database changes using tables/columns that are depricated.

Case for or against backwards compatibility

There are several opinions about this.

Increasing backwards compatibility may make the application more convoluted and perhaps harder to improve the code base long term. Conversely companies will be more willing to upgrade to more secure and later version.

Decreasing backwards compatibility ensures that the application is trimmed off its extra code and enforces developers to use the more modern features and readapt their customizations such as writing more compatible code or using Interfaces rather than concrete classes in the DI. It also however makes upgrades more costly and time consuming especially for smaller businesses.

How Magento does it

Relative to semver, it might sound strange that a x.y.Z-p incompatibility could introduce a major break, but realistically if you're running a server using a php-fpm of version 7.2 and upgrade Magento from 2.3.5 to 2.3.6 may break your website (P0) due to incompatibility with 7.3 and from 2.3.5 to 2.3.7 is extremely likely as there are are significant backward incompatibilities in php 7.4 with commonly used methods.
If you spent 1 minute looking at each of the release notes of 2.3.0 to 2.3.1, one may read

We are pleased to present Magento Open Source 2.3.1. This release includes over 200 functional fixes to the core product, over 500 pull requests contributed by the community, and over 30 security enhancements.

This means that a x.y.Z-p release has nothing to do with size or backwards compatibility and rather to do with improving whatever x.Y.z-p release intended. Where matters are complicated is when Y versions are upgraded in tandem and one starts seeing features brought in by Y+1 in Y version.

What Magento do is generally release a x.Y.z-p version and run it in tandem with a x.(Y-1).z-p version, which is upgraded seperately. There are surely reasons for this, it is likely to introduce several significant changes in one area while allowing some vendors with heavy customisations to get the upgrades necessary in smaller iterations. This is how you end up with versions like Magento 2.4.0 being behind Magento 2.3.7 especially when you look at version compatibilty of services like composer or Redis that support the instance running. This makes sense when you look at release dates. Magento 2.4.0 was released 28 Jul 2020, but Magento 2.3.7 was released at 11 May 2021. See https://github.com/magento/magento2/releases

See systems requirements: https://devdocs.magento.com/guides/v2.4/install-gde/system-requirements.html

Summary

A X.y.z-p version is wholly incompatible. It requires special purpose tools to migrate data and code or porting to a new instance.
A x.Y.z-p version upgrade is a very large release and usually a severe backward compatibility break, like a service incompatibility or removal/enforcement of services that support Magento, e.g. php version upgrade, or enforcement of elasticsearch for catalog indexing over mysql
A x.y.Z-p version, is a big release, but may still introduce severe backward compatibility break through incompatibility of services, code and database changes.
A x.y.z-P will include security fixes, which were orignally released on a patch list page on devdocs and installed via git patching. Explained in depth here. https://community.magento.com/t5/Magento-DevBlog/Introducing-the-New-Security-Patch-Release/ba-p/141287