Problem/Motivation
A large amount of our time during the Drupal 10 readiness effort was around semantic version discussions. Maintainers of contributed projects were creating new major version releases to add Drupal 10 compatibility while dropping Drupal 9 compatibility. That may technically follow semantic versioning guidelines but it adds profound complications for sites updating to a new Drupal core version.
For example, a site with a Composer requirement of "drupal/some_contrib_module": "^1.0" will have to explicitly change the version constraint if drupal/some_contrib_module releases version 2.0. In contrast, if drupal/some_contrib_module releases a new 1.x.x version when providing compatibility for the next version of Drupal core, sites trying to update Drupal core don't need to audit what's changed in drupal/some_contrib_module.
Therefore, contrib project maintainers should endeavor avoid new major versions except when absolutely necessary: (A) a code change introduces backwards compatibility breaking changes in the module itself or (B) a code change must drop backwards compatibility with a *supported* version of Drupal core. We shouldn't need to document (A), since that is covered by semver. We should establish a guideline for (B) -- i.e., for contributed projects and semantic versioning specific to Drupal core support.
Reference material
Derived from https://mglaman.dev/blog/drupal-module-semantic-versioning-drupal-core-s...
Proposed resolution
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
Remaining tasks
Decide where the documentation will fit into the existing docs. Add link.
Title of the page
Refine and agree on the proposed text