Semantic Versioning for Extensions

So you are either looking for the best way to provide versioning for your extensions or maybe you do have a working versioning system and are looking for ways to improve it. Every platform has its own name for it, be it modules, extensions, plugins, expansions. No matter the name, the problems with integrating different versions are the same in every platform. To keep it as simple as possible, we're refering to them as extensions.

This blog gives you our perspective on future-proof extension versioning. It does not matter if you develop extensions for Magento 2, WordPress, Drupal or any other third-party platform. This Semantic Versioning Model allows you to build a bulletproof solution which will work properly for years. It is designed to be able to be linked to the versioning of the platform, allowing customers to stay up to date without having to worry about installing a version which breaks due to platform incompatibility.

This blog is written from the perspective of Magento 2, but applies to any third-party platform which allows you to expand its functionality with dynamic extensions.

Magento 2: Our Own Situation

Magento requires us to use semantic versioning while our customer base is using a wide variety of Magento 2 versions. Updating to the latest Magento 2 version is not a simple task for many shop owners and we understand that. Either they do not have the knowledge internally to do this constantly or have a lengthy quality assurance process to ensure the revenue from the online shop keeps on flowing. There are a lot of reasons why there are still older Magento 2 shops in the market, which still require updates from extensions yet are usually no longer able to update their extensions due to the growing gap between the extension and the platform itself because the platform keeps on evolving just like the extension does.

Why not support JUST the latest version?
This is a question we sometimes get and the answer for this is because of 2 major reasons. At first, we want to provide the best service we can to ensure our customers can keep using our awesome extensions. And secondly our customers may want to purchase a compatibility release which we need to maintain. Therefor we need to ensure this release does not cause integrity problems in version control in the future.

The Semantic Versioning Model we designed

Now lets hop onto the good stuff and show you how the versioning system looks like. This is the exact model which we use to version our extensions.

We had to take a lot of factors into consideration:

      - The standard which we are required to use is that of SemVer. So our model had to use their schema
      - Our customers never needed to get an extension version for the wrong version of Magento 2
      - A customer needs to be able to setup a proper version constraint for their specific Magento 2 version
      - It needed to be possible at any stage to create compatibility for older versions of Magento 2 if a customer required it without affecting the latest extension version
      - The release information needed to be automated, so that we dont have to maintain version information manually on the website

You can Right-Click the image and open it in a new tab to view it more clearly.

Semantic Versioning for Magento 2 Extensions

So how does this versioning model work and why is it semantic?

Magento 2 has its own release cycle and extensions have to adapt to it as new releases are being made. The Magento 2 versioning model is also using SemVer, therefor, when Magento releases a new minor release, the backwards compatibility should stay in place. In reality, usually when Magento 2 upgrades the minor, it will come with breaking changes. Even patch upgrades sometimes result in backwards incompatibility issues. This results in extensions having a long list of version compatibility for each release a vendor makes, having to treat every patch release as a potential breaking change.

To allow us to link versioning to the right version of Magento 2, we use the Major to indicate what version of Magento 2 is compatible. followed up by our own minor and patch version

Automated Release Information

Since our website is its own dynamic composer repository and directly linked to version control, we needed to be able to fetch all the tags and enable the dynamic version list to be automated

To create a version list with all compatible Magento 2 versions, we fetch all the tags, we split it and list the versions by minor + patch version resulting in v1.0, v1.1 and so on with their respective compatible Magento 2 version.

Secondly, to instruct customers what version of extension to install, we use the same algorithm, to split the version numbers and create the proper version constraints for Magento 2 as described in the section below

Version Constraints

Using this model our customers can use the automated release information on our website to get the right version constraint for their Magento 2 version.

If the customer is using Magento 2.3.5, setting "^235.1.0" as version constraint will ensure he will always get the latest version of an extension with non-breaking changes for Magento 2.3.5, given that our extension has releases for it

A customer upgrading its webshop to Magento 2.5.0 at some point, would then upgrade the version constraint to "^250.1.0" and has the latest non-breaking change

At some point we will create breaking changes ourselves and that would result in a 2.0 version from our side, meaning a version similar to "250.2.0", which is working properly in Magento 2.5.0 but is not immediately backwards compatible with our 1.x version

If a customer has a reason to let us create a Magento 2.3.5 compatibility release for our "250.2.0", we create a branch for it and when its done, we tag it "235.2.0", allowing the customer to use the exact same version properly in his 2.3.5 installation

Automated version assumption
In our situation, if a version is specified as a "241.1.1" tag but has no separate tag for Magento 2.4.0 (240.1.1), a customer may safely assume that this latest release is also working properly in 2.4.0. In our case this is valid because we guarantee our latest version has a working version in all latest minor releases of Magento 2. In that case our website will list v1.1 to be compatible with Magento 2.4.x. This assumption can only be made safely if your company has policies about what versions of Magento 2 are supported. Because if somehow it doesnt work due to improper testing, you can create a branch in version control, fix the issues and release the version specific tag (240.1.1)

Share your thoughts

We know, It's not simple and there's multiple ways to provide a solid system for end-customers to get relyable updates. But what do you think? Are you already using a way of versioning which guarantees the integrity of the third party platform? Share your thoughts in the comments below