Skip to content

Contributing to GitLab Templates

If you want to contribute to the GitLab templates, use the main branch as reference, but work the issue queue, creating forks and merge requests so they can be tested and reviewed by others.

Tags

Branch name: main

When new features or bugs are committed, we might want to create new tags. We only have one branch (main), but we are following a semver approach to tagging releases, so the community can decide whether they want a fixed version, a recommended by the Drupal Association version, or the latest.

Release tagging strategy: X.Y.Z

We follow a linear development, but with tags so people can pin things:

  • If only new bugs were merged from the last tag, we increase the Z. ie: 1.0.1, 1.0.2... 1.0.11
  • If new features were added, we increase the Y. ie: from 1.0.11 to 1.1.0
  • Once a new "minor" tag is created (ie: 1.1.0), we don't port anything to 1.0.11
  • Breaking changes or a big refactoring increase X

For additional information on how contrib maintainers might use the above tags see the templates version page.

Maintainers only - semver tags and default tag

There is a script to help with setting up the tags located at scripts/do-git-tags.sh. Using this script will ensure that the desired tag is set and that also the moving tags for minor and major updates are updated too.

There is a special tag called default-ref that is the value set in $_GITLAB_TEMPLATES_REF. That tag can be set using the scripts/set-default-tag script. It will point to the recommended tag for the contrib space, so make sure that is a stable one.

Temporary code changes

When working on a fix or feature it is often necessary to make temporary changes. These can be done in a controlled manner, as follows:

Overriding the downstream pipeline variables

If you need to set variables temporarily to customize the downstream pipelines, this should be done in the assets/internal/downstream-variables.yml file. This file already has the most commonly required variables and they are commented out so that by default nothing is changed. Uncomment or add new variables as required. Using this file instead of directly setting the variables in the .gitlab-ci.yml file .downstream-base makes it clearer to see what is temporary and what is intended to be committed in the MR.

Use specific Gitlab Templates Downstream issue forks

By default, the Gitlab Templates Downstream (GTD) pipelines run from the canonical project repository. If the merge request needs to be tested against specific GTD issue fork branches, then change the pipeline definitions to set these. For example, change the last two line in:

'→ GTD D10 Theme':
  extends: .downstream-base
  trigger:
    strategy: depend
    project: project/gitlab_templates_downstream
    branch: d10-theme

to

    project: issue/gitlab_templates_downstream-3562055
    branch: 3562055-d10-theme

Marking other temporary code changes

If you need to add temporary echo statements or make any other temporary changes, add @temp, @temporary or @debug into the output string or comment to indicate that these changes are not to be committed.

Preventing accidental commit of temporary changes

To prevent accidental merging of any of the above temporary changes we have a custom pipeline job called Check Temporary Changes. This can be triggered manually at any time to check if the Merge Request contains any of the above temporary changes. It will end green if all is OK, but end with an amber warning if any temporary changes are detected.

This job is run automatically during a Merge Train, and if temporary changes are detected the Merge Train will be halted, thus preventing the unintended merging of the temporary changes.