[META] Support semantic versioning for extensions (modules, themes, etc) in Drupal core, and allow modules to be compatible with Drupal 8 and 9 at the same time

Created on 25 October 2018, over 6 years ago

Updated 6 November 2024, 8 months ago

Problem/Motivation

At #1612910: [policy, no patch] Switch to Semantic Versioning for Drupal contrib extensions (modules, themes, etc) → we finally decided to allow Drupal contrib extensions to use pure Semantic Versioning (SemVer). At over 400 comments, that issue is no longer useful to get anything done. ;)

This issue is the meta plan for tracking progress implementing the fixes to allow both semver and legacy versions within Drupal core. Drupal.org and packaging issues are tracked here: #2681459: Support contrib semver releases →

Proposed resolution

Documentation Updates

Everywhere we've documented "PatchLevel" we need to relabel as "Minor", for example What do version numbers mean on contributed modules and themes? → . PatchLevel and Minor are semantically equivalent, so we should eliminate confusion by having two semantically different things named "Patch" and "PatchLevel". There are a ton of other related docs that need to be updated to discuss this plan, explain / link to SemVer, etc.

Drupal 7

Drupal 7 contributed modules will continue to follow the existing pattern. 7.x-MAJOR.MINOR. For those user using composer to manage a drupal 7 site, the composer facade is able to translate this into a fake semver that composer can understand. For the users downloading files manually, or with tools like drush, they will still know that they are getting the drupal 7 version as it will be clearly marked.

Drupal.org

Drupal 8 contributed modules will allow for releases in the pattern of MAJOR.MINOR.PATCH. The composer facade and drupal.org will understand and allow for repository tags that include 8.x-MAJOR.MINOR (legacy), or MAJOR.MINOR.PATCH (fully compliant). Drupal core will need to be modified to expect and interpret these possibilities as well.

We have to fix Drupal.org to allow legacy (8.x-MAJOR.MINOR) and semver (MAJOR.MINOR.PATCH) versions on projects going forward. We'll probably have to retain the legacy support for a while, perhaps indefinitely.

see more #2681459: Support contrib semver releases →

5) Drupal 9 (maybe) we can deprecate the (9.x) part of the versioning scheme, as it may not even be accurate, and from that point forward, MAJOR.MINOR.PATCH will be the version numbers for drupal contrib projects, and dependency compatibility *must* be specified in the info.yml files (or composer.json if that's where we end up).

Remaining tasks

Core

Core needs to support semver dependencies, and the core Update module needs to support semantic version releases and development branches.

Must-have

Should-have

Could-have

(not needed but helpful) 📌 Convert update_calculate_project_update_status() into a class Needs work
(recommended for 9.1.x, and potentially 8.9.x/9.0.x if completed in time) #3005229: Provide optional support for using composer.json for dependency metadata →

Needs triage

Drupal.org

See #2681459: Support contrib semver releases → .

Documentation

As this moves forward, we'll need to update a lot of documentation.
(This list needs to be fleshed out):

User interface changes

TBD

API changes

TBD

Data model changes

TBD

🌱 Plan

Status

Active

Version

11.0 🔥

Component

extension system

Created by

🇺🇸United States dww

Live updates comments and jobs are added and updated live.

Composer

Drupal 9

Incomplete comments

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Comment 8 months ago →
🇦🇲Armenia murz Yerevan, Armenia
This issue 📌 Document how contrib hook_update_N() should be numbered now that modules can be compatible with multiple major branches and versioned semantically Fixed is closed, but from the current documentation it is still totally unclear about how to start numbering the hook_update_N() functions for modules, that use semantic versioning!

So, I created a separate issue ✨ Standartize numbering of hook_update_N following the module semantic versioning Active to improve this, please take a look.
Status changed to Needs review about 2 months ago1:01am 28 May 2025
Comment about 2 months ago →
🇳🇿New Zealand quietone
The must-haves and should-haves in the issue summary are complete and semantic versioning is supported. So, it seems to me that this can be closed. Should some or all of the child issue be moved to a new meta?

contrib.social Blog FAQ Discussions

Production build 0.71.5 2024