Changes to WooCommerce Versioning Scheme

tl;dr

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.

Background

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: MAJOR.MINOR.PATCH.
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.

Keep yourself in the loop!

10 responses to “Changes to WooCommerce Versioning Scheme”

Garconis

January 22, 2021

You say “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.”

But have you done any research/surveys to come to that conclusion?

I would assume — without surveying — that a good percentage of your WooCommerce plugin users (who are running the updates) are at least somewhat aware of the version numbers. Many WooCommerce users are at least somewhat tech savvy; not to mention the web dev companies that hosts 1000s of websites. They surely rely on SemVer to make informed decisions regarding updates and further research (e.g., checking changelog) before running said updates.

I realize you say you won’t be integrating any “breaking changes”. But major releases and major functionality still warrant SemVer scheme. While minor versions don’t warrant a bump up to the next “major version” number because you didn’t feel like bumping up to X.10.

Just my thoughts, but clearly the bulk of WooCommerce/Automattic doesn’t agree with these “industry standards”.

Reply
simbahosting

January 22, 2021

“Transitioning to WordPress versioning” appears to ultimately mean “transitioning to a scheme with no real meaning”. Using semantic versioning didn’t saddle anyone with a requirement to understand semantic versioning; but it did give a benefit to those who did. (On the flip side you could say that users are now saddled with a requirement to understand a scheme with no real meaning – surely that is worse?).

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.

Unfortunately this has been accompanied by the Github issue list ballooning to over 700 open issues. Monthly releases appears to mean that anything that doesn’t catch someone’s attention goes into Github issue purgatory and doesn’t return. When releases were 3-ish a year in the Mike Jolley era, he also cleaned the issue count down to zero at every release, and that was much better (if your issue wasn’t going to get any attention in a timely fashion, he’d just close it and explain why, rather than leaving it there forever…. a “priority: high” label doesn’t mean anything if it can stay in that state for over a year: https://github.com/woocommerce/woocommerce/issues?page=2&q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+high%22). Github misses you Mike!

Reply
1. Peter Fabian
  
  January 25, 2021
  
  Unfortunately this has been accompanied by the Github issue list ballooning to over 700 open issues. Monthly releases appear to mean that anything that doesn’t catch someone’s attention goes into Github issue purgatory and doesn’t return. When releases were 3-ish a year in the Mike Jolley era, he also cleaned the issue count down to zero at every release, and that was much better
  
  Thanks for sharing your view. You’re right in how you described the facts. I would like to add some background so that you’d better understand our reasoning and strategy.
  
  We definitely recognize this is not a good state of our repository and have a plan to address this problem. We’re going to keep a closer track of the issues we have in the repository and plan to eventually get them back to a more easily manageable state. With the core team responsible for shipping the core package that includes also WC Admin and Blocks, we have to divide our attention between delivering a high-quality WC core package and other responsibilities. We prioritized stability and well-tested releases that deliver value to our customers through new features regularly. Now that the process of releasing is fairly stable, we can look into fixing other areas we haven’t had so many opportunities to take care of, so we’re looking forward to addressing some of the long-standing issues we’ve unfortunately accumulated in the repository.
  
  Reply
  1. simbahosting
    
    January 30, 2021
    
    Hi Peter,
    
    Thank you for responding. Can I ask, what’s happened to order tables? Since the 3.0 release – almost 4 years ago – it has felt like WooCommerce has just decided to go for all the low-hanging fruit, accumulate more mom+pop stores, and ignore the deeper, long-running issues, like the bad performance once your store starts getting bigger. Github issues aren’t just “other areas”, they’re things causing the real-world users enough pain that they took the trouble to investigate and report.
    
    It was 2015 when order tables began being planned – https://github.com/woocommerce/woocommerce/issues/9735 – but instead of fixing core issues we keep getting shiny things like “a marketing hub” and extension suggestions instead (things which seem more like they’re coming from your own marketing overlords rather than a drive for overall quality). Perhaps that’s where the money is. But surely at 35% or whatever it is, of global commerce, there ought to be time and resources to focus on quality as well as on the other stuff? I am hoping that by “some of the long-standing issues” this (things like product tables, fixing other known non-scaling operations) the sort of thing you mean, so that running a larger shop isn’t a continual battle with known issues to patch them with home-brew customisations – issues that go years without seeing progress in core.
    
    Thanks again,
    David
    
    Reply
    1. M
      
      February 10, 2021
      
      I’m with Simbahosting from above and Steve Grunwell from below.
      
      I just saw that WC had a new version available and that it was version 5.0, so I went straight to the changelog, in part hoping to see a mention about the dedicated products and orders tables, but was astonished to see no big advancement (don’t get me wrong, I am not discounting all the work that has been put into this release) while the first digit of the version changed. Which made me reach for the WC Dev blog to discover THIS!
      
      It’s WP which should change its versioning not WC.
      
      Reply
Steve Grunwell

January 28, 2021

Overall, switching from Semantic Versioning to the WordPress versioning scheme feels like a big step backwards:

Even if less-technical users don’t understand the finer details of SemVer, it seems that upgrading from 4.9 => 5.0 feels like a bigger step than 4.9 => 4.10. It’s like updating to a new version of an operating system, or a device: “going from version 4 to version 5 means things might break, I’d better not risk it right away.” What’s worse is when some major new feature lands in something like 5.3 and users are caught off-guard.

If the goal is to reduce user friction, keeping SemVer seems to be the smarter move. Otherwise, you’re forcing users to pay close attention to the changelog for every minor release which, while they should be doing anyway, will more likely lead to update fatigue.

As an added benefit, those who do understand SemVer (read: the majority of the developer community and/or people even tangentially involved in software development and release cycles) can immediately see “oh, WooCommerce just bumped the major version, so we should put extra attention towards testing.”

By sticking with semantic versioning, WooCommerce also has the ability to say “hey, we’re making major architectural changes in this release (like CRUD in 3.0 or the eventual custom products + orders tables)” without it being a footnote in a changelog that most users aren’t going to read.

Please count me on #TeamSemVer.

Reply
Michael

February 15, 2021

As someone who has been involved in open source for the last decade, has had to make decisions regarding versioning strategies, and has felt the impact on versioning strategy decisions at an agency working with dozens of clients, I feel like this move at this point in WooCommerce’s lifecycle is a massive step backwards and only creates more confusion and frustration with your target audience.

These types of decisions really should be locked in early in a product’s lifecycle. Changing your versioning strategy after having long established a policy for how version numbers are incremented just creates frustration. Having seen 5.0 released, I was fully expecting a need to plan out our rolling upgrade to the new version for our clients using the software. I was surprised that Automattic had forced its versioning policy onto yet another product, especially one that had long established a versioning policy with Semantic Versioning. Now you have end users and developers and agencies who will have to understand the logic behind the policy in place when a specific version was released and work out what the policy is for the version being upgraded to (because in the real world, not every site is blindly updated on release day to the newest version, contrary to what some in the WordPress ecosystem would like to see).

The commitment to backward compatibility is applaudable, however the Semantic Versioning strategy that had previously been in place (and I argue used successfully since its implementation) was still more than appropriate for the product. About the only benefit to abandoning Semantic Versioning in favor of WordPress Versioning is the faster moving major version number which from a marketing perspective doesn’t allow for a product to seem stale if that number is being arbitrarily incremented at a set interval. Beyond that, you’ve now made it harder for your consumers to be aware of breaking changes and we are now forced to treat every minor version increment as a major upgrade with the potential of backward compatibility breaking changes since your version strategy is now effectively “we do what we want”.

Reply
1. sarumbear
  
  February 24, 2021
  
  I couldn’t have said it better than Michael. Arrogance is a menace that eventually kills companies.
  
  About the only benefit to abandoning Semantic Versioning in favor of WordPress Versioning is the faster moving major version number which from a marketing perspective doesn’t allow for a product to seem stale if that number is being arbitrarily incremented at a set interval. Beyond that, you’ve now made it harder for your consumers to be aware of breaking changes and we are now forced to treat every minor version increment as a major upgrade with the potential of backward compatibility breaking changes since your version strategy is now effectively “we do what we want”.
  
  Reply
sarumbear

February 24, 2021

This is a step backwards! Your logic is false and I haven’t heard you doing any research or user poll on this either.

WP and WC are software products. Anyone who is involved with software MUST have at least a rudimentary knowledge of how updates work.

You should have updated WP to SM instead.

Reply
chyvak1831

March 5, 2021

I’m agree with people above – it’s totally unclear now when will be breaking changes appears.

Reply