Merge branch 'add-commitlint-template' into 'master'

Add commitlint template

Closes #55

See merge request !64

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2023-10-16
+
+### Added
+
+- `commitlint.yml` template to ensure the [Conventional
+  Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard is adhered
+  to for projects who wish to use it.
+
 ## [3.0.0] - 2023-08-09
 
 ### Changed

commitlint.yml

+# This template will run commitlint against commits. By default, it uses the Conventional Commit specification via the
+# .commitlintrc config file baked into our commitlint docker image. However, you can override this config by simply
+# creating your own .commitlintrc file in the root of your git repository. .commitlintrc can be either yaml or json
+# format.
+
+# The template contains the following two jobs.
+#
+# The `commitlint` job is the main job. This job runs for both merge request pipelines and branch pipelines. When in a
+# merge request pipeline it uses the helpful `$CI_MERGE_REQUEST_DIFF_BASE_SHA` variable to determine the point in
+# history to begin linting commits. When in a branch based pipeline, the job assumes that the branch will eventually be
+# merged into the default branch and uses `git merge-base` to determine the point at which the branch was originally
+# forked and lints all commits from that point.
+#
+# The `commitlint-hotfix` job only runs for branches named `hotfix-*`. When patching a bug in a previous release a
+# hotfix branch is often forked from a git tag. Therefore, this job finds the latest tag on the branch using `git
+# describe` and lints all commits from that point.
+
+.commitlint-base:
+  image: registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/commitlint:latest
+  stage: test
+  variables:
+    GIT_STRATEGY: clone
+    GIT_DEPTH: 0
+  before_script: |
+    # If the cloned repository doesn't have a .commitlintrc we use our default one which is baked into our
+    # commitlint image. Note that .commitlintrc can be either a yaml or json formatted file.
+    if [ ! -f ".commitlintrc" ]; then
+      COMMITLINT_OPTIONS="--config /opt/devops/.commitlintrc ${COMMITLINT_OPTIONS}"
+    fi
+
+    # By default, GitLab performs a shallow clone of the target repository and checks out a detached commit rather than
+    # the branch itself. We want to be able to search the full history to determine the nearest parent branch so we
+    # need to do the following.
+    git fetch origin
+    git checkout "$CI_COMMIT_REF_NAME"
+  # This job doesn't need to wait for the build stage.
+  needs: []
+
+commitlint:
+  extends: .commitlint-base
+  script: |
+    # This job supports both branch and merge request pipelines. If we're in a merge request pipeline we can use the
+    # helpful "CI_MERGE_REQUEST_DIFF_BASE_SHA" variable to lint all commits that are part of the merge request.
+    if [ -n "$CI_MERGE_REQUEST_IID" ]; then
+      FROM="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
+    else
+      FROM="$(git merge-base --fork-point origin/$CI_DEFAULT_BRANCH $CI_COMMIT_BRANCH)"
+    fi
+
+    npx commitlint --from "$FROM" --verbose $COMMITLINT_OPTIONS
+  rules:
+      - if: $COMMITLINT_DISABLED || ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH) || ($CI_COMMIT_BRANCH =~ /^release-it--.*$/i)
+        when: never
+      - if: ($CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH !~ /^hotfix-.*$/i) || $CI_MERGE_REQUEST_IID
+        # Initially this job is for information only and we don't want to force pipelines to fail with incorrect commit
+        # messages so we set allow_failure to true.
+        allow_failure: true
+
+commitlint-hotfix:
+  extends: .commitlint-base
+  script: |
+    # This job is specifically for hotfix branches. Hotfix branches should be forked from a git tag to patch an issue,
+    # therefore, this finds the most recent tag and lints all commits from that point.
+    FROM="$(git describe --tags --abbrev=0)"
+
+    npx commitlint --from "$FROM" --verbose $COMMITLINT_OPTIONS
+  rules:
+      - if: $COMMITLINT_HOTFIX_DISABLED
+        when: never
+      - if: $CI_COMMIT_BRANCH =~ /^hotfix-.*$/i
+        # Initially this job is for information only and we don't want to force pipelines to fail with incorrect commit
+        # messages so we set allow_failure to true.
+        allow_failure: true