Guidelines for semantic versioning for contributed projects in relation to Drupal core compatibility

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 #3238652: [policy] Decide how long major Drupal versions should be supported - Drupal 10 will have security support years into Drupal 11, so explicitly dropping Drupal 10 support probably will justify a new major version except for the very smallest modules that wait until Drupal 10 is EOL.

+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.

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.)

Composer will keep you on a version that supports 9.5 anyway.

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 composer's dependency system and by 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.

This means that even if you wanted to continue to provide security support for Drupal 9 sites, there's space to do so with a 1.2.1 release etc.

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 contrib modules 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
2. Drop support for any minor version of Drupal core or unsupported versions of Drupal core.
3. 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

Since this issue is focused on how **contributed projects** should apply semantic versioning, I've added that to the issue title, and replaced "core support" with "core compatibility" to better reflect what I believe the focus of this issue is, i.e., whether to specify a major or minor release when adding/dropping compatibility with versions of Drupal core.

Since this issue really seems to be scoped to guidelines about semver for contrib projects when their code changes the relationship to Drupal core, I think it would be more actionable for people if it didn't try to cover all scenarios for major/minor/patch releases. The following narrows the scope here to only prescribe behaviors when code changes its relationship to Drupal core. I've updated the issue description with this proposal, too:

A contributed project should release a new major version when its code changes the relationship to Drupal core by:

• Dropping compatibility for a currently supported version of Drupal core
• Introducing breaking changes from Symfony or another dependency where backward compatibility (such as adding types to method signatures) cannot be supported.
• Introducing impossible dependency resolution (such as the module requiring Guzzle 7 when a previous Drupal core version required Guzzle 6).

A contributed project should release a new minor version when its code changes the relationship to Drupal core by:

• Dropping compatibility with an unsupported version of Drupal core.

A contributed project should release a new patch version when its code changes the relationship to Drupal core by:

• Adding compatibility with a new Drupal core major version while maintaining backward compatibility for all previously supported versions

#17 looks very clear and sensible to me.

The Ideas project is being deprecated. This issue is moved to the Drupal project. Check that the selected component is correct. Also, add the relevant tags, especially any 'needs manager review' tags.

Thanks

I think the issue summary is great, so I'm moving this to RTBC - where would this be documented on Drupal.org?

This is something that the technical working group would have been responsible for at one point but that's not a functioning group as such now, and anecdotally I know a lot of contrib modules are following this already or very close to it, and very regularly see people asking for advice on how to manage it.

Updating status per 22, I've not reviewed this myself.

I put the documentation at Guidelines for semantic versioning for contributed projects in the Creating a new project.

I did made some changes to make it easier to scan the page and added a into paragraph. The page is set to NR.

I updated the remaining tasks.

And then I noticed that I missed the suggestion by @joachim about a new guide. That seems like a good idea, but it is not strictly necessary to complete this piece of work. The doc can easily be moved later.

That looks good, agreed the page itself can be moved around later.

Thanks! Looking good.

Note, this is also related to https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... also. Wonder if it should cross link?

It's directly related to https://www.drupal.org/handbook/cvs/releases which used to exist, but is now a 404. 😢 Not sure whatever happened with those docs.

Sorta related to https://www.drupal.org/docs/7/choosing-a-drupal-version/overview#contrib also, but that seems stale (note the "7" in the URL, although I don't know why it's tied to legacy Drupal).

I didn't know about https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or.... And I think this content fits better in that guide.

I am assigning this to myself to move the doc next week.

Should we also talk about other dependencies?

For example, if a Commerce ecosystem module wants to add support for Commerce 3, and then drop support for Commerce 2 -- do the same principles apply?

Sigh, another issue I forgot about for longer than intended.

The content, the proposed resolution, has been moved. It is now at Managing branches & releases. A URL redirect created for the previous page and that page has been deleted. I think that covers the work for this issue. Back to RTBC.

@joachim, good point. Perhaps a new Documentation project issue or a even a conversation in Slack can lead to doc updates to incoporate that case.

https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... looks great.

I keep looking at this issue (it's the oldest in the RTBC queue) and thinking what's left to be done, and deciding it's probably nothing, but then not being quite confident enough that it's done. But we can tweak this documentation if we need to either via another issue or directly, so going to go ahead and mark fixed.

I think this guidance needs to be revisited, given that the realities around implementing forward compatibility for Drupal 12 are starting to result in "patch" releases with up to thousands of lines of API-level code updates migrating procedural hooks to OO (or occasionally even just a few dozen such lines that still break anyway).

This also conflicts with official SemVer.org guidance:

Bug fixes not affecting the API increment the patch version, backward compatible API additions/changes increment the minor version, and backward incompatible API changes increment the major version.

Forward compatibility changes for OO hooks belong in a minor version, not a patch version. A patch release is only supposed to fix bugs and security issues. By shipping large API changes in a patch release, contributed modules incrementing their patch version are now more likely to be broken than they were before.

Applying forward compatibility in a minor release instead does not prevent upgrading the module along with Drupal core when caret versioning is used.

(Deleted the following because I realized after the fact that the first paragraph of the guidance does say "contributed projects should also support more than one major core version," though this could be made clearer in the "major version" bullets)

Additionally, the guidance as it stands still has a gap: The point was to allow a project to upgrade to a new Drupal core major version without also needing to update the Composer requires for its modules. However, there is no requirement for a forward-compatible release as a patch version before dropping the previous still-supported major. A module could still have v1.0.0 support Drupal 10, while v2.0.0 supports Drupal 11, with no version that supports both.

The SemVer.org guidance addresses this gap, but if familiarity with SemVer is to be assumed then we should fix the d.o guidance so it doesn't contradict SemVer when defining patch releases.

Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

@caesius thank you.

To be honest most of what you mention is all bc friendly, the hook ordering can be tricky, but most everything else can be done in a minor version for contrib.

The project update bot just provides the fixes, it doesn't decide what version to release it in.

A module could still have v1.0.0 support Drupal 10, while v2.0.0 supports Drupal 11, with no version that supports both.

I'll be honest, while this is true, in practice it makes core updates far more complicated.

It's also becoming more commonly required because you have to jump minor versions for core, e.g. 10.6 has to update to 11.4 minimum.

I've updated two clients in the last week and they've required jumping through composer hoops on a few contrib dependencies because of this.

I am open to discussing mprovements to the docs though, we can always improve!

I think coming up with guidance that produces the least friction depends on understanding both the intent behind SemVer and developer expectations in practice.

In SemVer, minor versions aren't supposed to be breaking. It's just "here's some new features for you to use." In that case, why would anyone ever hesitate to update to the newest minor version as soon as it's available? Surely it's just as safe to use as a patch-level bugfix release, right?

Except, as we all know, that's not quite the case. Adding new features introduces more moving parts that could break. But in terms of the Drupal-specific SemVer guidance, that's not even what happens, either: A minor version that drops support for Drupal 8+9 just needs to make a one-line change to a .info.yml file. Meanwhile applying a patch version for Drupal 12 compatibility means grabbing a module that's been Ship-of-Theseus'd. Even if the invocation of the public API hasn't changed, can you really say it's still the same API?

The disconnect means you don't really know what you're getting when updating your modules unless you go look at release notes. A patch release could be a one-line bugfix or 1,000 lines of D12 compatibility. A minor release could add shiny new features or just drop unsupported Drupal versions. Obviously, any module updates on client sites should be tested before going to prod, but if a patch version can come through with the same sort of re-piping that you'd see in a major release, then every module release needs to be treated with the same degree of vigilance regardless of the version jump, and there's no point in applying "only patch releases" as part of routine updates.

The following seems to me like the easiest scenario to deal with when considering both routine module updates and Drupal core upgrades, and the guidance could be rewritten to enforce the scenario exactly:

Drupal 9: EOL
D10, 11: Current
D12: Future

• 3.1.1: ^9 || ^10 || ^11 final 3.1.x release
• 3.2.0: ^10 || ^11 identical to 3.1.1, just with ^9 dropped from .info.yml. Keep the rule to increment minor versions when dropping support.
• ... development happens ...
• 3.5.0: ^10 || ^11 adds tentative Drupal 12 compatibility. Any code refactor needed for forward compatibility gets a minor release.
• ... development happens, D12 officially releases, D10 goes EOL ...
• 3.8.5: ^10 || ^11 || ^12 identical to 3.8.4 release, one-line .info.yml change to indicate D12 compatibility. If the actual module code does not need to change to support a new Drupal major, it can be a patch release. If you needed to make additional code changes to support D12 then it needs a new minor instead.
• ... development happens ...
• 3.10.0: ^11 || ^12 one-line change to .info.yml to officially drop D10 support
• 3.10.1: ^11 || ^12 D10 BC layer removed. Removing BC is probably safer than adding FC, but I could see this being a new minor instead, and I think most modules would drop ^10 at the same time as killing the BC layer.

Alternatively, using a major version they could still drop support for Drupal 10 sooner than EOL. However, they will need to have had both Drupal 10 and 11 compatibility present on the previous major, unless there is a good reason that their module needs to be upgraded at the same time as Drupal and skipped the BC phase.

I've created #3621138 to formally propose making changes, the discussion can continue there.