Guidelines for semantic versioning and Drupal core support

It might be a silly question but based on what I read from your article, for someone who has created a Drupal 7 module following the convention 7.x-X.Y and now trying to upgrade that module for Drupal 10, is the recommendation using semver to just use 1.0.0 or 2.0.0 instead of 10.x-X.Y?

This came up briefly at the committer offsite as well. +1 to adding official docs that recommend this approach.

One idea we had was to ask the DA to implement a 'badge' system similar to security opt-in so that project maintainers can self-declare that they follow these guidelines. That way when people install a module for the first time, they'd have a better idea how smooth major upgrades will be with it.

It is a fairly minor disagreement but there is one thing from the blog post I'm not convinced by:

When Drupal 9.5.0 was released, we decided to stop supporting 9.0.x, 9.1.x, and 9.2.x, and remove all that backward compatibility cruft. I consider this a minor version change. Why? Those versions of Drupal core no longer have security support. Dropping unsupported minor versions of Drupal core should not break your public APIs and only change how they function internally.

vs.

Major versions

• Deciding to drop the previous major version and all backward compatibility layers

Once 9.5.x is out of support in December, then " Dropping unsupported minor versions of Drupal core should not break your public APIs and only change how they function internally" applies equally to 9.5 as it does to 9.2. So I am not sure that dropping 9.5 and PHP < 8.1 after 9.5 is EOL requires a new major version either.

But what makes this even more minor is 🌱 [policy] Decide how long major Drupal versions should be supported Needs review - Drupal 10 will have security support years into Drupal 11, so explicitly dropping Drupal 10 support probably will justify a new major version.

+1.

This is a similar idea to the best practice for contrib modules that was developed in the pre-8 era. Views and CCK for D6 took a VERY long time to be released, because the maintainers were doing an internal rewrite at the same time as a D6 rewrite. After that experience, people realised that the best thing to do was to update only the Drupal core compatibility, then do a rewrite during the Drupal core cycle. So:

- 6.x-1.x
- 7.x-1.x (only the Drupal core-facing parts updated)
- 7.x-2.x (do a major rewrite during the 7 cycle)

What we're suggesting here is similar. We can sum up both concepts as: 'Change as little as possible when bridging between two core versions.'

Where is this documentation to live?

I often find it easier to review some existing text than to start anew. Therefor, I have copied text from @mglaman's blog post and added it to the Issue Summary as a starting point. I did tweak the sentences a bit as if it would be in documentation.

I would assume somewhere under https://www.drupal.org/docs/develop → , maybe a new 'versioning' heading under https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... → ?

I'd say a new section on https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... → called 'Releases', and then a page within that.

In time, the 'Releases' section could also do with things about security releases and version numbers in general.

Honestly what level to bump upon dropping PHP and Core is a bit of a controversial subject, even in the semver issue queue.. Part of this was because it was originally designed to handle libraries only, not end-user utilized software, so some of the concepts of versioning where not worded as broadly as might be needed.

If this is to go forward as a badge I request that there be two versions available "Strict Semver Complaint" (for those who belive major releases need to be cut when dropping Core and PHP support) and "Drupal Semver compliant" (for those who believe dropping a version of Core/PHP is an acceptable behavior in a minor or bugfix release).

For the majority of users it won't matter which it is and they will be happy with both, but for some it will be really helpful to know just how 'strict' the semver is for a module to help us decide what modules to use and what modules to avoid.

Before I start I want to mention that Semver is also more than just your method signatures. If i have method foo() that is documented as doing A/B/C and I change it to do unrelated D/E/F instead is it really API compatible? No of course not.

So I am not sure that dropping 9.5 and PHP < 8.1 after 9.5 is EOL requires a new major version either.

I'll note that semver is NOT suppose to consider if a software is EOL or not with regards to the change..

In my eyes just because Drupal Core or a version of PHP is no longer supported doesn't mean you can just ignore the compatibility when it comes to semver versioning as it relates to your versioning. When your designing a module you are NOT designing it for a version of Drupal, you are designing it to work with a Drupal Comptatible API that just so happens to match the Drupal Version. Just like Ubuntu Linux supports very long life backports of security updates for programs, its very possible some commercial support vendor could still supports D8 customers, this is part of the reason why you can't consider the official EOL status to let you off the hook for supporting without it being assumed breaking somewhere.

Semver is suppose to at its root covey the risk of that if you changed nothing and ran the program how well would it work. If I'm already on the latest Drupal Core and Latest php its low risk for EOL versions to be dropped, if I'm not its a major risk of breakage and that why dropping version support should signal a Major release in that case to inform me I need to look very closely at the release notes.

You as a developer don't have to support that old usage, but you do need to signal to your users that you intend to break that old usage. As a site owner I expect if version 3.0.0 of a module works on Drupal 9.5 than version 3.99.1 should also work (even if D9.5 is EOL and I haven't used it on my site in 5 years, I should be able to fire it up and load 3.99.1 and it works.)

You can generally update your dependencies in a library and be just fine under semver, however in my eyes Drupal Core is NOT a dependencies for most modules, its the operating environment (the exception to this rule is Distributions which are their own Drupal package.) Worded another way, you don't install a module to make your entire site, you install a module to be a part of the site as such the module shouldn't be deciding what specific path of core you run, just like it shouldn't be deciding what Distribution of LInux I'm running in my test lab.

Before I start I want to mention that Semver is also more than just your method signatures. If i have method foo() that is documented as doing A/B/C and I change it to do unrelated D/E/F instead is it really API compatible? No of course not.

@cmlara this is not what the semver spec actually says, see point 1:
https://semver.org/

1 Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.

What is considered as an API break, is changes which diverge from the documented public API, it's up to the project to determine what exactly the public API is - Drupal has different rules for interfaces, public methods, protected methods, constructors, controllers, plugins etc. because of this. So does Symfony.

So if you document that your public API does not cover whether or not EOL versions of Drupal core are supported, then that doesn't require a major version increment.

Honestly what level to bump upon dropping PHP and Core is a bit of a controversial subject, even in the semver issue queue

As a potential case study, our team at the University of Texas → , which maintains 20 contrib modules, is planning to follow the methodology laid out by Matt Glaman in the original blog post as-is until a recommendation is finalized on drupal.org. The table below shows some of those modules, their latest release number and Drupal compatibility.

1. No other code changes will be included in the next release of these modules, other than Drupal 11 compatibility. However, we plan to drop support for Drupal 8 & 9 concurrent with providing compatibility with Drupal 11. As such, following the guidelines proposed by Matt Glaman, that will mean major version releases for all of the modules.
2. We accept that this will require sites to change their Composer version constraints for these modules to be able to update to Drupal 11. But the output from composer update will provide accurate information about dependency resolution, so that should not be opaque or out of the ordinary for dependency management.

Current version numbers (pre Drupal 11 support / Drupal 8/9 drop)

Don't go making major version changes

I have major issues with the conclusion in Matt's blog post, as made by comment #12. I cannot understate the problems caused by making new major releases, especially if you have a dependent module ecosystem. Think about Drupal core: every 2 years or so the community has to make this massive change to every module to remain compatible with Drupal core. By adopting the suggestion in Matt's blog, every contrib module and site has to not only become compatible with Drupal core, but with all the other contrib modules. Instead of one target (core), you're chasing multiple targets (your dependencies) that all update at different timeframes.

Additionally, your major version now is tied to Drupal core and not your API, and if you're making major API/architectural changes, you now have another set of major versions to maintain.

Bad:

Within 3 years, you could see the following:
layout_builder_restrictions 8.x-2.x --> Drupal 9.3, 10
layout_builder_restrictions 3.x -> Drupal 10, 11
layout_builder_restrictions 4.x -> Drupal 10, 11 --> New API changes
layout_builder_restrictions 5.x -> Drupal 11, 12

The result of this mess is that people cannot update their sites easily, especially if another module they depend on hasn't updated their dependencies other than core.

Better:

layout_builder_restrictions 8.x-2.20 -> Drupal 9.3, 10 LAST RELEASE for DRUPAL 9
layout_builder_restrictions 8.x-2.21 -> Drupal 10, 11
layout_builder_restrictions 3.0.0 -> Drupal 10, 11 (NEW API CHANGES)
layout_builder_restrictions 3.1.0 -> Drupal 11, 12

If I have a Drupal 9.3 site with layout_builder_restrictions 8.x-2.20 installed, this is the last version of layout_builder_restrictions I can use on this site until I upgrade to Drupal 10 or 11. The fact that I removed the Drupal 9 BC code in layout_builder_restrictions 8.x-2.21 is not a problem because it will not install on a Drupal 9 site.

You as a developer don't have to support that old usage, but you do need to signal to your users that you intend to break that old usage. As a site owner I expect if version 3.0.0 of a module works on Drupal 9.5 than version 3.99.1 should also work (even if D9.5 is EOL and I haven't used it on my site in 5 years, I should be able to fire it up and load 3.99.1 and it works.)

Disagree. I expect that composer will install the most recent version of a module I specify that is compatible with my site. I also expect that the version that gets installed will work with my site... meaning that if the module removes support in code for my version of Drupal, it also updated composer to ensure that version will not install on my site either.

If we follow this logic, then what about contrib dependencies? Should I make new major versions of my module when an upstream dependency makes a new major version? If geofield makes a new major version, how do I know if the upstream major version is an API change vs a Drupal core change? Would geofield_map need a new major version? You can see how this cascades into a mess of new major versions that becomes untenable. This is why contrib major version releases should be reserved for its own API/product major changes rather than what its dependent on.

You can and should drop previous Drupal versions in minor releases

Unlike code and API changes, upstream dependencies are managed by composer. Thus, removing BC code and upping the minimum requirements will not cause breaking code. Why? because the new version will not install on unsupported sites!

Unless you plan to actively support and make releases for the no longer supported version of Drupal, there is no point in making a new branch and subsequent release. Even if you do plan on making future releases, you could do it with minor releases (1.1.x support 9.5, 10, 11 vs 1.2.x supporting 10, 11)

Same with PHP

PHP version support should follow core's requirements. If your module supports Drupal 9.5, it needs to support PHP 7.4. Its fine to introduce support for newer versions of PHP as long as it doesn't break the minimum requirements. Dropping php support should follow core: Once you support Drupal 10 as a minimum, PHP 8.1 is minimum. Nothing changes here in regards to major/minor version changes; removing Drupal 9.5 from composer means no Drupal 9 site will get your new version, despite it being only a minor release.

Why is this important?

Modules do not exist in a vacuum. They live in this larger ecosystem with sites and other modules dependent on their code to work. When core and modules make new major versions, it fractures our ecosystem → . As contrib maintainers, we should do everything we can to minimize the dependency pathways by adding BC shims, supporting core versions of Drupal at least until EOL (if not slightly past), and when we do drop support, rely on composers dependency system and not making new major versions unless the module's API/architecture is changing.

Yes I personally agree with #13, at least once a module is using three digit release numbers, dropping support for a completely unsupported release of Drupal core seems fine to me, and means there wouldn't be the same knock-on effect on dependent modules. e.g.

Based on statements in #13 and #14, it seems we have a strong sense that new major version releases of contributed modules create significant work on the part of individual site maintainers. As a consequence, we should set forth a guideline that recommends creating new major versions of contribs module ONLY in situations where the module introduces changes that require configuration or code changes in the site using that module.

Under this principle, a module release that simply drops support for an UNSUPPORTED version of Drupal core should NOT trigger a major version increment.

A revised version of the proposed guidelines follows, along with an interdiff of what would change.

Major versions

1. Drop a supported major version of Drupal core and all backward compatibility layers
2. Breaking changes from Symfony or other dependency that cannot have backward compatibility support (such as adding types to method signatures.)
3. Impossible dependency resolution (such as supporting Guzzle 6 and 7 at the same time.)

Minor versions

1. Add support for a new major version of Drupal core while dropping a minor version of Drupal core, or unsupported previous versions of Drupal core.
2. Add major new features and want to provide a minor version out of caution for users

Patch versions

1. Add support for new Drupal core major version, with backward compatibility
2. Other bug fixes
3. Small features