Adopt (semver) versioning for gitlab_templates
Problem/Motivation
The gitlab_templates are intended to be the base for modules implementing tests on G.D.O. With DrupalCi deprecated the gitlab_templates should no longer be treated as a pre-release and instead should be regarded as a full stable project.
Maintainers are encouraged to modify them as necessary to suite their projects needs.
This puts us in a spot where the templates need to be treated as API where we are able to control how we announce breaking changes and control adoption to a set time.
We have had occasions where we have intentionally restructured (likely breaking tests), accidentally broken deployments[#3390764 (closed)], and where we are discussing if we should care if we break existing deployments #3400979: Is SYMFONY_DEPRECATIONS_HELPER: weak correct for contrib deprecation testing needs?
It is my understanding we originally created the use of $_GITLAB_TEMPLATES_REF to allow some control over ensuring we do not break contrib deployments, however since it was added in the late stage alpha/beta we have left it on the 1.0.x branch rather than tag specific releases and maintain a versioned release process.
Having a well defined policy will allow us to better review changes, and provide more stability for users to ensure that the gitlab_templates remain used.
Breaking changes to the CI have a negative impact to maintainers who will need to stop a dev cycle in order to fix the CI environment before other issues can proceed. This can be especially damaging during the window between beta1 and stable release of core where contrib needs to adopt any necessary changes.
Excessive breaking changes could lead to maintainers abandoning gitlab_templates as a base instead opting to control the templates completely on their own, this would reduces the ability for the DA to push out performance optimizing changes, security fixes, or publish new new features to encourage cleaner code,
Steps to reproduce
N/A
Proposed resolution
Formally adopt semver compatible release numbering and process associated with it.
Create a new branch for each 'major' dev cycle.
Tag periodic points as X.Y.Z where we want to trigger a new adoption and update the $_GITLAB_TEMPLATES_REF value (we may be able to instead include a dedicated 'versions' branch that only contains version numbers of the branches instead of updating the global values)
Move tags as necessary to update for X and X.Y aliases.
Any change that will remove existing features, or will knowingly break existing CI runs will be a new major (Exception: there may be cases where bugs cause tests to pass when they shouldn't, these could be bug fixes not major changes.)
Any change that adds new features without breaking existing runs (such as adding phpstan in an allowed to fail state) will be a Minor
Any change that fixes bugs will be a Patch (such as changing sudo to be sudo -E to pass environment variables.)
As per semver, should a fix be found to breach the above rules, revert it, tag a new release, and open up a new dev cycle for the fix in the correct version location..
Final implemented version
The ref: value can be set to:
-
ref: $_GITLAB_TEMPLATES_REF- This is the recommended (and default) value. The Drupal Association will update this value to the recommended tag for contrib -
ref: 1.0.0- a fixed known tag value. This will not move and not get any updates. It is up to the maintainer to change this when necessary -
ref: 1.0.x-latest- Get the latest additions but only within a Minor (mostly bugfixes) -
ref: 1.x-latest- Get the latest changes but only within the Major version (will include bugs and new features) -
ref: main- Get the very latest additions and bug fixes as soon as they are merged into the templates
User interface changes
None
API changes
Creation of an 'api' for the gitlab_templates repo.
Data model changes
TBD
Related issue: Issue #3400979
Related issue: Issue #3390764