de en
← Back to Articles

Semantic versioning

Semantic Versioning - Teaser
Pixel & Tonic will convert Craft CMS and Craft Commerce to semantic versioning in the future. But what does that mean exactly and what are the advantages and disadvantages for developers and consumers?

Since 3.0, developers have tried to avoid extensive changes in the documented APIs. But various plugins and modules made unexpected problems, causing every major change to have unintended consequences.

Craft 3.0 has been available for 2.5 years, and in that time, there have been five major releases, some with far-reaching changes. To the customer, it's just an update from 3.2 to 3.5, but a lot has happened under the hood, and perhaps there are issues with plugins that, in the worst case, cause the site to stop working. Especially WordPress service providers know this problem.

With Craft 4 and Commerce 4, Pixel & Tonic is changing, as they call the major updates. Around twice a year, there should be these updates, which are then treated as major releases. Say the following update with far-reaching changes and innovations after Craft 4.0 will be 5.0 and not 4.1.

This means:

  • Plugin developers must publish updates indicating which Craft versions they are compatible with.
  • Web developers can update websites to the latest Craft version after all installed plugins have released compatibility updates. This is to prevent a website from malfunctioning due to an incompatible plugin.
  • This will also make it easier to find out which plugins are no longer distributed by the developers, as they will not receive updates for the next Craft version.

There will also be minor releases in the future, but these will only improve small things:

  • X.0.0 (Major): Major changes and innovations, such as Craft 3.4 and 3.5. About twice a year.
  • X.Y.0 (Minor): Minor changes with updates that don't make problems. They are released every few weeks.
  • XYZ (Patch): Pure bug fixes that will be released in the short term if necessary.


Semantic versioning can be beneficial since all major releases must be compatible. And the minor releases must not have any breaking changes. For the user, the great advantage should be that you can make clear statements in the future about whether plugins and CMS will be compatible with each other. If not, one can look for plugin alternatives or explore other solutions at an early stage.

The previous version jump from 3.1 to 3.2 is sometimes considered too small by customers or private users and, therefore, quickly clicked on update. If the change is from 3.X to 4.X, there may be more respect, and if not with the customer, then with the service provider, who is more likely to read the release notes before the update.

Especially in the first years after the changeover, I expect confused customers if, within one year, Craft 4 and then Craft 5 are updated. The following year you would have Craft 6 and 7, and so forth. On the positive side, this also shows how actively Craft CMS is maintained and improved. The times when a successor with a new version number appears every few years and this release is celebrated accordingly are also over. We live in times of subscription models like Adobe Creative Cloud or PhpStorm. The high version number we will have in the Craft ecosystem in a few years is also something you quickly get used to. As a comparison, I like to refer to iOS and the iPhone

However, conservative souls will miss the perceived security that Craft 3 radiated: A system that will soon be a faithful companion for three years, but where major changes such as Craft 3.5 may have been somewhat lost.

Photo from  Thomas Sausen<

Self-employed web developer from Germany who started with WordPress websites in 2005, then moved to ExpressionEngine and lost his heart to Craft CMS in 2013. As the founder of Craftentries, he has been covering the Craft ecosystem since 2015.

Thomas Sausen Web Developer