localgovdrupal
Introduce major versions of LocalGov Drupal align to Drupal Core version
Context
The LocalGov Drupal project maintains a Drupal quickstart project and profile that depends on specific versions of Drupal Core. As Drupal Core evolves, compatibility issues and patch differences arise that cannot be seamlessly managed through minor or patch versioning alone. Maintaining a single version stream would complicate dependency management, introduce instability during upgrades, and make it difficult to align contributed and custom module updates with their respective core compatibility.
A versioning strategy is required to align LocalGov Drupal releases with Drupal Core. Further info around patching difficult can be found here.
Decision
Major versions will be used for the LocalGov Drupal profile and project to correspond to the major versions of Drupal Core. Each major version of LocalGov Drupal will align with the equivalent major version of Drupal Core.
As implemented in https://github.com/localgovdrupal/localgov/issues/870#issuecomment-3323296397 this will look like;
- LocalGov Drupal (project and profile) 3.x for Drupal Core 10
- LocalGov Drupal (project and profile) 4.x for Drupal Core 11
- LocalGov Drupal (project and profile) 5.x for breaking changes in LocalGov as well as supporting Drupal Core 11
This approach ensures that patches, dependencies, and configuration differences can be maintained separately without cross-contamination or complex conditional logic in the codebase.
Consequences
Adopting major version alignment with Drupal Core simplifies long-term maintenance and improves clarity for contributors and adopters. It enables clean separation of compatibility layers, facilitating a smoother upgrade process when transitioning between Drupal Core versions. However, it requires additional release management effort and clear documentation to guide users in upgrading between LocalGov Drupal major versions, as breaking changes may occur between each aligned release.
Side note
As part of this I'm currently writing a page for the documentation page that explains this further along wth support timelines
@millnut Does this mean that we couldn't have any breaking changes to, for example, LocalGov 4.x until Drupal 12 gets released? Like, we couldn't release a bumped version to LocalGov 5.x during 11?
Hi @markconroy I guess it depends on the level of breaking change, what we are talking about specifically here is aligning a LGD major version to a Drupal core version to make it easier for cross version Drupal Core patches and patches for contrib modules which have specific versions for Drupal Core.
Currently we have had abit of a patch nightmare due to 3.x supporting both D10 and D11 (we now have a 4.x to replace 3.2.x for D11). Continuing with this approach, we follow other distributions such as Thunder, OpenSocial and other distributions for the same reason.
Personally I'd like us to move away from patch URLs and have them within the codebase as .patch files that way we could declare versions with specific patch files but that would need a wider discussion. This also follows the Drupal GitLab guidance https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal/downloading-a-patch-file#s-use-downloaded-patch-files as MR patches can change.
We could still release a LocalGov 5.x for 11 if we wanted to introduce breaking changes, as this isn't restricting us to a single major version to a single core version. I've updated the examples to make this clearer.
In practice. Localgov 1.x => Druapl 8 Localgov 2.x => Drupal 9 Localgov 3.x => Drupal 10.
So we have been doing that already. It was the Drupal 11 upgrade that was different as there wasn't a need to (initially) create new modules for Drupal 11. It would however have meant that if a site did not have strict dependencies on Drupal 10, it could have forced an unplanned upgrade. So I'd say it makes sense to keep profiles in step with Drupal core releases. At the cost that this is strictly speaking not semantic versioning (pending a breaking change which would require new major?)
This also raises the question of what happens when we need to make a major release of modules and themes. We have precedent now with Localgov_base about allowing two versions in the profile. Would we want to formalise that as it means work on events and directories 4 can be uncoupled from the profile without requiring a major upgrade. However it means the Finders version will get installed automatically once that is available. (I'd be more in favour of this though, as you can always explicitly require the version in a sites root composer.json).
An alternative would be to move to regular (annual / six month) major releases that support the latest only of what is released, with a support timeline of 1 year of bug fixes. Which would make site upgrades more predictable.
I agree @andybroomfield when it comes to modules that have major versions there are extra considerations such as how long do we support the previous version for and what cadence do we introduce breaking change major versions for modules. As well as allowing users enough time to upgrade and to be more predictable on when major versions would occur
Discussing this in the Tech Governance meeting and no objections @millnut
One thing we do want to do is:
Write some guidelines for versioning of contrib modules . For example, localgov_events and localgov_directories requiring finders. How do we deal with this and communicate this?
Agree @finnlewis we should use major versions for those.
But also for the finders module we could look into declaring a composer conflict (https://getcomposer.org/doc/04-schema.md#conflict) for older versions of localgov_events and localgov_directories that way when the localgov profile is updated to support both 3 or 4 of those modules we have a safeguard along side the breaking change messaging on the localgov profile release notes to flag that the big changes to events and directories are included and to stay on existing versions add it to the root composer.