Problem/Motivation
Drupal modules and themes need to be able to specify that they depend on specific versions of Drupal because a new minor version of Drupal may introduce new APIs and a patch version may fix bugs. Drupal modules and themes also should be able to specify if they are compatible with 2 major versions of Drupal such as 8 and 9, if they don't use any APIs that will be removed in Drupal 9. Modules, install profiles and themes should not have to create a new major branches to achieve this as per #2608062: [META] Requirements for opening the Drupal 9 branch.
For Drupal 8 projects, currently the core key in info.yml files only supports core: 8.x which denotes that they support any version of Drupal 8. To get around this limitation many modules use the dependencies: key in info.yml files with a more specific version of system module. For example- "drupal:system (>8.6)". But this method is not enough because it does not support patch releases either, see #2641658: Module version dependency in .info.yml is ineffective for patch releases.
While we could change the core: key to accept semantic version constraints to allow requiring specific core patch versions, for example core: ^8.7, or even support multiple branch compatibility (core: ^8 || ^9), or both (core: ^8.7 || ^9) this would cause problems for any sites using previous versions of Drupal 8 core, if they attempted to update a module they currently have installed that switched to the new format.
A Drupal 8.x.y site that has my_module 8.x-1.1 that uses core: 8.x and then updates to my_module 8.x-1.2 that uses core: ^8 (anything beside 8.x) will have this this module silently disabled, even while the configuration for the module would still be available. There would be no message that this happened. See #138 and #2917600: Disabling missing modules results in a "Unable to install MODULE already exists in active configuration" warning or PreExistingConfigException (via Drush).
Proposed resolution
As a consequence of the above, we need to introduce a new key core_version_requirement: that would accept Composer semantic version constraints. The version constraints will be evaluated by \Composer\Semver\Semver::satisfies(). The rules for this can be found at https://getcomposer.org/doc/articles/versions.md.
This key could be used at the same time as the core: key. But in certain cases it would be used in place of the core: key. To make it possible to have modules be compatible Drupal 8.7.x, 8.8.x, 8.9.x and 9.0.x and maximize the duration in which Drupal 9 readiness can be worked on and ensure that security fixes for contrib modules don't force sites still on Drupal 8.7.x to upgrade to Drupal 8.8.x (if the module doing a security release already started using core_version_requirement). See reasoning in #179.3 and release manager approval in #207.
Assuming the 8.7 patch release in which this issue ships is 8.7.7, the following combination would not produce the expected results info.yml file:
core: 8.x
core_version_requirement: ^8.7.7
This would not actually restrict anyone from installing it on Drupal 8.6.x, or 8.7.0 through 8.7.6 since the core_version_requirement key would be ignored and would therefore still allow the module to be installed. We cover this case by not allowing the core: key once a core_version_requirement key requires Drupal 8.7.7 or later. Not having the core: key will give a hard fail in Drupal 8.7.x sites but because it fails in \Drupal\Core\Extension\InfoParserDynamic::parse this would not cause a problem in #138 and #2917600: Disabling missing modules results in a "Unable to install MODULE already exists in active configuration" warning or PreExistingConfigException (via Drush).
Another combination that would not produce the expected results:
core: 8.x
core_version_requirement: ^8.7.4
In this case Drupal 8.7.3 would not enforce core_version_requirement: ^8.7.4. We enforce this by not allowing restrictions that cover versions before this issue is committed because these will not actually be enforced.
In both these cases it would be hard for a contrib author to be aware for these problems if they are working on Drupal 8.8.x unless they also tested their module on previous versions of Drupal. Therefore we should add validation to \Drupal\Core\Extension\InfoParserDynamic::parse() to make sure that module authors don't create info files with these problems.
Examples of supported core_version_requirement: values:
core_version_requirement: value | Evaluates to constraints | Comments |
|---|---|---|
| ^8.8 | >= 8.8.0.0-dev < 9.0.0.0-dev | Recommended for modules that are only compatible with 8.8.x and above but not 9. |
| ^8 || ^9 | >= 8.0.0.0-dev < 10.0.0.0-dev | Recommended for modules that are compatible with both Drupal 8 & 9. Most modules aren't actually compatible with all versions of Drupal if removed deprecated API use and used the new replacements. |
Remaining tasks
User interface changes
Small string change for modules page.
API changes
Support core semantic versioning for Drupal core via new core_version_requirement key.
Data model changes
None.
Release notes snippet
A new core_version_requirement has been added to info.yml files. This key replaces the core key for projects that only support Drupal 8.8 onwards (including Drupal 9). It may be used in addition to the core key for projects that want to specify compatibility with Drupal 9 as well (but remain compatible with prior versions of Drupal 8). Read more at https://www.drupal.org/node/3070687