Drupal 8.7.7 adds semantic versioning support

One of the changes introduced with the launch of Drupal 8.7.7 included support for semantic versioning. The Semantic Versioning specification was originally authored by Tom Preston-Werner, inventor of Gravatar and cofounder of GitHub. We are currently on Semantic Versioning 2.0.0.

First introduced in Drupal 8.7.7 the new core_version_requirement key in *.info.yml files for modules, themes, and profiles now supports semantic versioning as implemented by the Composer project. This allows modules, themes, and profiles to also specify that they are compatible with multiple major versions of Drupal core.

For example a module that is compatible with Drupal 8 and Drupal 9 can have a info.yml file like this

name: My Module
type: module
core: 8.x
core_version_requirement: ^8 || ^9

This specifies that the module is compatible with all versions of Drupal 8 and 9. The core: is required here because Drupal Core versions before 8.7.7 do not recognize the core_version_requirement: key.

Most modules however will have to remove deprecated code to be compatible with Drupal 9. Therefore they will not able to be compatible with all versions of Drupal 8.

For example a module that is compatible with Drupal 8 versions after Drupal 8.8.0 and also Drupal 9 will need a info.yml file like this:

name: My Module
type: module
core_version_requirement: ^8.8 || ^9

The core: key must not be used here to make sure that versions of Drupal before 8.7.7 will not install the module. Adding both core and core_version_requirement with anything other than core_version_requirement: ^8 || ^9 will result in an exception.

The core_version_requirement cannot be used to restrict to core version before 8.7.7. For instance, core_version_requirement: ^8.7 || ^9 would throw a parsing exception: This is not valid because ^8.7 would include versions like 8.7.0 which do not recognize the core_version_requirement: key.

It is also possible to specify the same requirement in composer.json, but if no drupal/core requirement is defined there, one will automatically be generated based on core_version_requirement. 

{
  "require": {
    "drupal/core": "^8.7.7 || ^9"
  }
}

Drupal's project_composer provides an adaptor for modules hosted on drupal.org to the composer command line utility. It is intended to be run on drupal.org infrastructure to provide a shim that can translate drupal modules, submodules and their drupal specific versioning scheme into something that can be consumed by the composer command line utility. It aims to have API parity with packagist.org as far as the composer command line tool is concerned.

Ok so we can see that in Drupal prior to 8.7.7 module versions were effectively shimmed with the patched part effectively being ignored. 

So we can see that it would be better to not have to patch the version in order to make use of semantic versioning. This change basically that code change will definitely be required in your module or theme in order to support the new use of semantic versioning in Drupal 9.

Transitioning from 8.x.-* to x.y.x

Since Drupal 8, projects can be compatible with any range of Drupal core versions. So 8.x-* releases and releases using semantic versioning occupy the same space for version numbers. Put another way, a 8.x-1.0 release is effectively the same as 1.0.0

When your project switches to using semantic versioning, you must increment your major version. For example, if the latest release is 8.x-3.5, your next stable release will be 4.0.0

(The converse is also restricted, once 4.0.0 is released, you can’t release 8.x-4.0 or 8.x-5.0)

8.x-* projects can be compatible with Drupal 9, so you don’t need to switch right away if you aren’t ready to start a new major version release series.

Most versions of Drupal 8 are not compatible with semantic versioning. If your project supports Drupal 8.8.3 or lower, don’t switch to semantic versioning.

9.x-* and later releases can not be made. Since most releases made now are likely to be compatible with multiple versions of Drupal core, the API compatibility prefixes don’t make sense to keep. Use semantic versioning for any release only compatible with Drupal 9 or higher.

With semantic versioning, composer.json and core_version_requirement are used to define a release’s requirement for Drupal core.

https://www.drupal.org/node/1015226#semver-transition

Summary

So we can see that since Drupal 8.7.7 support for semantic versioning gives the ability for Drupal modules, themes and profiles to

1. Work across multiple versions of drupal core, (currently 8/9. Versions of modules are no longer constrained to the version of Drupal! That said this really means modules could run on >8.7.7. and > 9.0.0
2. Eliminate dependency of drupal's project composer shim that does not utilise the patch version number
3. Support for patch numbers
4. Introduces a new  new core_version_requirement key in *.info.yml to specify the multiple major versions of Drupal core.that it is  compatible with
5. the core key is still a requirement for modules that continue to run on versions prior to 8.7.7 - but adding both core and core_version_requirement with anything other than core_version_requirement: ^8 || ^9 will result in an exception - in other words you cannot use core_version_requirement: ^8.6 || ^9. 

The decision to introduce semantic versioning prior to launching Drupal 9.0.0 was probably a good one that allowed modules maintainers to prepare themselves prior to looking at other changes moving from 8-9, as well as offering compatibility between the two major versions of Drupal and a kinder upgrade path.