WooCommerce Core and related ecosystem plugins are transitioning away from Semantic Versioning and adopting WordPress versioning. This transition will begin with WooCommerce 5.0, which will be a non-breaking change.
A few years ago, WooCommerce adopted a Semantic Versioning (SemVer) scheme for its releases. This adoption marked an improvement from what had been a relatively opaque incremental versioning system that often intermixed fixes, new features, and breaking changes. You can read more about that SemVer adoption and the rationale behind it in this announcement post from 2017.
Much has changed in the past four years, and, after much internal deliberation, WooCommerce is transitioning away from SemVer and adopting WordPress versioning for releases of WooCommerce core and any related ecosystem plugins. We understand that this transition will have an impact on developers who build with WooCommerce, so we wanted to provide additional context about the reasons behind this decision, what will be changing, and what action developers need to take.
How is WordPress-style versioning different from SemVer?
SemVer uses a delimited trio of version numbers that each increment according to a set of shared principles and rules outlined in the SemVer Specification. To paraphrase that specification:
- A normal version number must take the form:
- Patch versions must increment when you release backwards-compatible bug fixes.
- Minor versions must increment when you add new functionality that is backwards compatible.
- Major versions must increment when you introduce backwards incompatible changes.
WordPress versioning appears similar at a glance; it too takes the form of a delimited trio of version numbers (e.g.
5.5.3). The meaning behind these numbers is where the primary difference lies. Under WordPress versioning:
- The first delimiter essentially functions as a decimal point, so the first two numbers increment like a standard base-10 counter with each major release. Because of this, the second number will never go above 10.
- The third number represents a minor release and is intended primarily for bug fixes. This number may occasionally go beyond 10 if there are many fixes to a particular release.
- Most importantly, changes to the first number do not signify backwards incompatible changes. To put that another way, the distinction that exists in SemVer between major and minor releases does not exist in WordPress versioning. Under WordPress versioning, all normal (i.e. major) releases are treated equally, and backwards incompatible changes are avoided at all costs.
Why are we making this change?
Focusing on the merchant experience
Because WooCommerce is built atop (and operates within) the WordPress ecosystem, it’s beneficial for merchants if our platform reflects the standards and conventions that WordPress establishes upstream. This leads to a more consistent and predictable user experience long term.
Semantic Versioning is a valuable tool for developers, perhaps most notably because it provides a universal shorthand for deducing the nature of differences between two different versions of software and, in more practical terms, the likelihood that an update will intentionally break some piece of existing functionality. Saddling merchants with the responsibility of understanding the nuances of SemVer, often just to determine whether or not they should update their store’s software, adds unnecessary friction to their user experience.
Instead of asking merchants to monitor and compare the version numbers of the software they use, we believe we should put energy into helping merchants feel confident pushing the update button so they can focus on what’s most important to them.
Prioritizing backwards compatibility
Keeping with the idea of making releases as safe as possible, we are adopting WordPress versioning as part of a larger ongoing effort to prioritize backwards compatibility in WooCommerce. SemVer provides an easy pathway for introducing backwards incompatible changes by attaching them to a major release.
While breaking changes are unavoidable in many cases, WordPress’ commitment to avoid backwards incompatible changes is something that has allowed the community and platform to flourish over the years in ways that other platforms have not. As our platform continues to evolve and grow alongside WordPress, adopting WordPress’ equal-weighted versioning scheme is both a signal that we are committed to backwards compatibility and a practical measure that we are taking to eliminate the pathways through which breaking changes could reach unsuspecting merchants.
We realize that committing to backwards compatibility introduces a significant amount of technical debt, but we believe the value this provides to merchants makes the tradeoff worth it. For navigating breaking changes that will inevitably need to occur, we believe there are alternative approaches to SemVer that minimize the impact to merchants.
Communicating explicitly rather than implicitly
A big factor in those alternative approaches relates to the way we communicate about changes to WooCommerce. SemVer is, at its heart, a tool for implicitly communicating high-level information about a particular version of software. Because of this, it’s easy for us as developers to rely on a version number to imply something that we should instead be communicating explicitly using things like documentation, deprecation warnings, and migration paths.
Over the past year, the WooCommerce core team has transitioned to a monthly release cycle, which prevents the kind of code accumulation that we had seen when releasing less frequently. This monthly cadence also helps us detect potential conflicts and incompatibilities with more ease and consistency so we can provide explicit communication about issues and guidance for developers and merchants who may need to make accommodations for upcoming releases.
What is changing?
WooCommerce core will be adopting WordPress versioning with its next release, which is currently slated for February 9, 2021. This means that there will not be a WooCommerce 4.10. The next release will be WooCommerce 5.0, and this release will not be a breaking change.
Other WooCommerce ecosystem extensions will be transitioning to WordPress versioning as well, but the timelines for adoption vary among the the teams who maintain those extensions. When an extension transitions from SemVer to WordPress versioning, we will be sure to indicate this clearly in the extension’s changelog.
What is not changing?
While we are moving away from SemVer for merchant-facing software, our teams will continue to use SemVer for developer-oriented software such as NPM packages and certain Composer packages. These packages are largely handled by automated dependency-management systems that merchants don’t interact with (and which rely on SemVer to load specific versions).
What action do I need to take?
Recent WooCommerce releases up through version 4.9.1 include code that parses version numbers for available updates according to SemVer rules. This behavior was recently deactivated with a fix that will land in version 4.9.2, which is slated for release the week of January 25th.
We recommend stores update to WooCommerce 4.9.2 before WooCommerce 5.0 is released on February 8, 2021. If a store tries to update from an earlier version directly to WooCommerce 5.0, they’ll see spurious notices in their admin area warning them that WooCommerce 5.0 is a major release.
Because all regular releases going forward will have the same weight, developers should keep the new versioning scheme in mind and make appropriate adjustments if they have implemented any solutions that rely on there being a distinction between major and minor WooCommerce version numbers.
We recognize that this a significant shift, and we are eager to hear any feedback or questions you have. You can share your input in the comments below, or reach out to us in our Community Slack. We’ll also be dedicating time to this topic in our upcoming monthly Developer Community Chat. Keep an eye on this blog for a post with additional details.