With the release of Shopware 6.3, we are also switching to more strict adherence to Semantic Versioning. And with good reason, this switch will help us be more in line with the standards of the PHP community and will make it more clear to you as a developer whether a release introduces any breaking changes, or if it is safe to apply.
Let's dive into the details of this change.
A short refresher on why it makes sense at all to assign version numbers to software and how the versioning strategy of Shopware looked like so far can be read here in the fold-out menu
Semantic Versioning, or SemVer for short, has been adopted by many programing communities as an industry standard, and for good reason.
The SemVer version number is a form of communication. The first thing it tells you is that there is a timeline for a software product. The product undergoes changes, and these changes are happening in a somewhat orderly manner. Usually, these changes made to the product are collected and bundled into a periodic release. These releases are then versioned.
A new version is always a release; a defined state with a trackable set of changes that makes it different from the version before.
At Shopware, we use a distributed version control system to keep track of these changes, called git. Every time a change is made to the software, it is added to git. If Shopware has accumulated enough changes, a new tag is created in git. A tag is a way to say, "Hey, let's give this current state of the product a referrable name". These tags then become a release with a version number.
All this is important for several reasons: You don't want to implement every change to your shop as soon as it is added to Shopware. At the time of writing this article, there are, on average, 18 changes per day in Shopware 6. And those changes may contain code that will break the functionality of plugins that are not yet adapted to the changes.
A release version does more than give you a nicely packaged set of changes. It promises that these changes are tested and signed off on. For example, a breaking change scenario might be, a change in the way the shopping cart handles taxes which leads to orders not being correctly displayed in the administration because of a dependency upgrade in the node dependencies.
So, in a nutshell, Versioning is about promises and communication.
Before the upcoming release of Shopware 126.96.36.199, a new version of Shopware could contain breaking changes, security patches, and bugfixes all mixed in together. Shopware settled on a very telling and reliable versioning scheme with Shopware 188.8.131.52 (Some of you may notice that additional 0 at the end already).
This mix of changes means that a version number tells you not much more than the existence of changes and the probability of them affecting your system.
Shopware used a sequence-based version schema. The big number at the start indicates the major version. Upgrades between these numbers are not possible, they require code to be completely rewritten.
The latest example of this is the jump from 5 to 6: It's an almost entirely new technological base.
The new Shopware versioning system
Shopware implemented SemVer as "SemVer with benefits".
SemVer (semantic versioning) is a specification that defines a version number and, more importantly, the importance of an incrementation of a version number.
A SemVer compliant version has three numbers: Major, Minor, and Patch. They are incremented following this ruleset:
- MAJOR: Incompatible API changes are made
- MINOR: Functionality is added in a backward-compatible manner
- PATCH: Backward-compatible bug fixes are made
The "with benefits" part is: We keep the big marketing number. So Shopware 6 still is the product, but there's a Shopware 184.108.40.206. With 3.0.0 being the SemVer part.
The public API
These indicators of versioning apply to something called the "public API". This public API is the Shopware code a theme or extension is communicating with. That can be the REST API, but there is also an internal API or the public methods that cover the core functionality, used by plugins.
This is important since a change that introduces breaking changes to code that is not considered public API would only increment the PATCH number. Luckily, since using the non-public API is regarded as bad practice, this should not impact well-written themes and plugins. But still, there is no safety net when it comes to software updates - always use a staging system.
Shopware release cycle
With the new versioning system, the release cycle of Shopware changes as well. The new Shopware versions will release once a month. This can include new features, but it can also be a simple patch-release. While the new and exciting features are still announced and marketed, you now get them potentially earlier or, in some cases, later, but in a more mature state.
All that does not mean merchants should upgrade their shops once a month. It means features and patches are more frequently released, including all the support and testing they deserve.
Merchants and SemVer
Apart from any versioning schema, it is always essential to test updates in a staging system before applying them to the live shop.
That said, as a merchant, you get more reliable information from now on.
When the last two numbers change, you can install the new version without the fear of breaking anything. A change from 220.127.116.11 to 18.104.22.168 would only contain bug fixes, a change from 22.214.171.124 to 126.96.36.199 would include feature additions, but without breaking anything.
Plugin developer and SemVer
What do I have to consider as a plugin developer?
With the new adjustments, we will no longer publish a "Release Candidate" in the future. Plugin developers will be able to view the current development status at any time via the master branch on GitHub and check the compatibility of their plugins.
Plugin compatibility can still be controlled via Composer. We recommend one of the following scenarios:
~6.3.0: With this configuration, the plugin would be marked as compatible for all minor versions within the 6.3 major cycle. This includes all minor and patch versions in the 6.3.x.x grid.
~188.8.131.52: Even if all minor versions are backward compatible, there might be changes in logic from time to time. If you want to make sure that a plugin is compatible with a certain minor version, you can mark your plugin for certain minor versions by specifying four digits. The plugin is then compatible with all 6.3.1.x patch versions within the minor version.
Detailed information about the version configuration can also be found in the official documentation of Composer.
The 184.108.40.206 update is planned for the beginning of August, with which these new adjustments will come into effect.
If you have any questions regarding the new Shopware versioning schema, please head over to our community workspace in Slack and tell us!