Revise SemVer guidelines for contributed projects

Problem/Motivation

The Managing branches and releases docs covering semantic versioning in contributed projects should be reviewed and revised in order to realign Drupal's definition of PATCH-level releases with official SemVer guidance.

The current guidance states that adding support for a new Drupal core major version is done in a PATCH-level release. The practical implications of this conflict with SemVer:

MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

This is because the drupal.org guidance implicitly asserts that adding forward compatibility is a "bug fix," even though it could easily be argued to "add functionality" instead and therefore merit a MINOR release.

If forward compatibility refactoring is instead defined as a minor-level change, no new friction would be introduced when it comes to reconciling module versions with new Drupal majors in Composer.

Background

In Issue #3357742 guidelines for semantic versioning in contributed projects were drafted which introduce rules for how specific release versions should relate to Drupal core compatibility.

The issue referenced a blog post which made the following claim:

Patch versions

Adding support for new Drupal core majors! Technically it's a bug fix, when you use add backward compatibility (which you should be!)

The blog offered no source or specific argument for why adding support for a new Drupal core major version is "technically a bug fix" that belongs in a patch release rather than a new feature that would belong in a minor release.

At the time the guidelines were being considered, automated Drupal 11 compatibility issues were getting filed en masse, and Drupal 10 compatibility work was fresh in mind. For the most part, modules did not require much in the way of code updates in order to become Drupal 10 or 11 compatible.

Drupal 12 compatibility fixes, however, are proving to be more complex than what came before. Procedural hooks need to be migrated to object-oriented hooks. You need to register a new service for these hooks and annotate LegacyHooks for D11+. These fixes are intended to be backward compatible and non-breaking, which means they certainly do not belong in a major release, but whether they should be in a patch or minor release still needs further discussion and consensus.

The original motivation behind drafting the new guidance focused on restricting modules from dropping EOL Drupal majors in a patch release, or neglecting a backward-compatibility bridge when dropping support for a supported Drupal major. The decision to define forward-compatibility as a patch-level change did not appear to be specifically discussed.

Refer to latest discussions in #3357742 for additional arguments.

Proposed resolution

Update the guidance to redefine forward-compatibility refactoring as a minor-level change. Implementing forward compatibility in a way that does not require substantial code updates may be patch-level instead, especially if a necessary refactor was already implemented in a previous minor version release.

Also update the guidance to reiterate and reinforce the requirement for a module to support two major Drupal versions and specifically state how that is to be done when a module decides to drop support in a major release.

Proposed revisions; changes are emphasized:

Major version

• Dropping compatibility for a currently supported version of Drupal core
  • Support may only be dropped in the stable release of a new major module version if a previous module major already provides forward compatibility.
  • Support for the previous module major must continue until either the new major provides backward compatibility or until the dropped Drupal version is End-of-Life.
• remaining two bullets remain unchanged

Minor version

• Dropping compatibility with an unsupported version of Drupal core
• Refactoring module code to support a new Drupal major while retaining backward compatibility for all previously supported versions
  • The minor release may formally begin support for the new Drupal major concurrently, or defer formal support to a future patch release.

Patch version

• Adding compatibility with Introducing formal support for a new Drupal core major version while maintaining backward compatibility for all previously supported versions
  • Only when module code otherwise remains substantially unchanged, such as when refactoring was already done in a previous minor release. Forward compatibility refactoring requires a new minor version instead.
• Removing a vestigial backward compatibility layer for a Drupal major whose module support had already been dropped in a previous major or minor release.

Remaining tasks

Discuss the proposal and come to a consensus.

Should the guidance actually change, promulgate the new standard.