From dfea8470837e6d77a3c1098e9d00fd25a44b5bf4 Mon Sep 17 00:00:00 2001
From: Daniel Dehennin <daniel.dehennin@ac-dijon.fr>
Date: Mon, 11 Oct 2021 14:49:45 +0200
Subject: [PATCH] ci(gitlab): add commit lint and its documentation
* .gitlab-ci.yml: define only stage `lint` for now and run
`commitlint` at that stage.
* docs/CONTRIBUTING.md: describe the commit message formatting rules.
* README.md: link to the contributing guide.
---
.gitlab-ci.yml | 36 ++++++++++++
README.md | 10 +++-
commitlint.config.js | 8 +++
docs/CONTRIBUTING.md | 134 +++++++++++++++++++++++++++++++++++++++++++
4 files changed, 187 insertions(+), 1 deletion(-)
create mode 100644 .gitlab-ci.yml
create mode 100644 commitlint.config.js
create mode 100644 docs/CONTRIBUTING.md
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 0000000..87d3586
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+# vim: ft=yaml
+---
+
+###############################################################################
+# Define stages and global variables
+###############################################################################
+default:
+ tags:
+ - one
+ - eole
+ - docker
+
+stages:
+ - lint
+variables:
+ DOCKER_DRIVER: 'overlay2'
+
+commitlint:
+ stage: lint
+ image: 'hub.eole.education/eole/commitlint:latest'
+ before_script:
+ # Add `upstream` remote to get access to `upstream/master`
+ - "git remote show upstream 2> /dev/null || git remote add upstream ${CI_REPOSITORY_URL}"
+ - 'git fetch --all'
+ after_script:
+ # Remove `upstream` to avoid caching `CI_JOB_TOKEN`
+ - "git remote remove upstream"
+ script:
+ # Set default commit hashes for `--from` and `--to`
+ - 'export COMMITLINT_FROM="$(git merge-base upstream/master HEAD)"'
+ - 'export COMMITLINT_TO="${CI_COMMIT_SHA}"'
+ # Run `commitlint`
+ - 'commitlint --from "${COMMITLINT_FROM}"
+ --to "${COMMITLINT_TO}"
+ --verbose'
diff --git a/README.md b/README.md
index 4a4731c..91a3f6d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
# CI tools
-Tools for the Gitlab CI
\ No newline at end of file
+Tools for the Gitlab CI
+
+## Contributing to this project
+
+### Commit messages
+
+Commit messages formatting is **significant**!
+
+Please, see [How to contribute](docs/CONTRIBUTING.md) for more details
diff --git a/commitlint.config.js b/commitlint.config.js
new file mode 100644
index 0000000..4eb37f4
--- /dev/null
+++ b/commitlint.config.js
@@ -0,0 +1,8 @@
+module.exports = {
+ extends: ['@commitlint/config-conventional'],
+ rules: {
+ 'body-max-line-length': [2, 'always', 120],
+ 'footer-max-line-length': [2, 'always', 120],
+ 'header-max-length': [2, 'always', 72],
+ },
+};
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..04ca1d4
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,134 @@
+# How to contribute
+
+This document will eventually outline all aspects of guidance to make your
+contributing experience a fruitful and enjoyable one. What it already contains
+is information about commit message formatting and how that directly affects
+the numerous automated processes that are used for this repo. It also covers
+how to contribute to this project documentation.
+
+[[_TOC_]]
+
+## Overview
+
+
+Submitting a merge request is more than just code! To achieve a quality
+product, the tests and documentation need to be updated as well. An excellent
+merge request will include these in the changes, wherever relevant.
+
+
+## Commit message formatting
+
+Since every type of change requires making Git commits, we will start by
+covering the importance of ensuring that all of your commit messages are in the
+correct format.
+
+### Automation of multiple processes
+
+This project uses
+[semantic-release](https://github.com/semantic-release/semantic-release) for
+automating numerous processes such as bumping the version number appropriately,
+creating new tags/releases and updating the changelog. The entire process
+relies on the structure of commit messages to determine the version bump, which
+is then used for the rest of the automation.
+
+Full details are available in the upstream docs regarding
+the [Conventionnal Commit Message Conventions](https://www.conventionalcommits.org/en/v1.0.0/).
+The key factor is that the first line of the commit message must follow this format:
+
+```
+type(scope): subject
+```
+
+For example:
+
+```
+feat(libfoo): new API `foo.quux` deprecates `foo.bar`
+
+We create the new API `foo.quux` to better do things and mark
+`foo.bar` deprecated from version `1.3.4`.
+
+* test/libfoo.t: test the new API `foo.quux`
+
+* lib/foo.pl: new API `foo.quux` and mark `foo.bar` deprecated.
+```
+
+Besides the version bump, the changelog and release notes are formatted
+accordingly. So based on the example above:
+
+> Features
+>
+> - **libfoo**: new API `foo.quux` deprecates `foo.bar`
+
+- The `type` translates into a `Features` sub-heading.
+- The `(scope)`: will be shown in bold text without the brackets.
+- The `subject` follows the `scope` as standard text.
+
+### Linting commit messages in CI
+
+This project uses
+[commitlint](https://github.com/conventional-changelog/commitlint) for checking
+commit messages during CI testing. This ensures that they are in accordance
+with the
+[semantic-release](https://github.com/semantic-release/semantic-release)
+settings.
+
+For more details about the default settings, refer back to
+the [`commitlint` reference rules](https://conventional-changelog.github.io/commitlint/#/reference-rules).
+
+
+### Relationship between commit type and version bump
+
+This project applies some customisation to the defaults, as outlined in the
+table below, based upon the type of the commit:
+
+| Type | Heading | Description | Bump (default) | Bump (custom) |
+|----------|--------------------------|---------------------------------------------------------------------------------------------------------|----------------|---------------|
+| build | Build System | Changes related to the build system | – | _ |
+| chore | – | Changes to the build process or auxiliary tools and libraries such as documentation generation | – | _ |
+| ci | Continuous Integration | Changes to the continuous integration configuration | – | _ |
+| docs | Documentation | Documentation only changes | – | 0.0.1 |
+| feat | Features | A new feature | 0.1.0 | 0.1.0 |
+| fix | Bug Fixes | A bug fix | 0.0.1 | 0.0.1 |
+| perf | Performance Improvements | A code change that improves performance | 0.0.1 | 0.0.1 |
+| refactor | Code Refactoring | A code change that neither fixes a bug nor adds a feature | – | 0.0.1 |
+| revert | Reverts | A commit used to revert a previous commit | – | 0.0.1 |
+| style | Styles | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) | – | 0.0.1 |
+| test | Tests | Adding missing or correcting existing tests | – | 0.0.1 |
+
+
+#### Scopes
+
+Even if it is possible to
+[limit the possible scopes](https://github.com/conventional-changelog/commitlint/blob/master/docs/reference-rules.md#scope-enum)
+like [in Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#scope),
+this project does not enforce them and let the contributors define meaningful
+ones in their commits.
+
+### Use `BREAKING CHANGE` to trigger a `major` version change
+
+Adding `BREAKING CHANGE` to the footer of the extended description of the
+commit message will **always** trigger a `major` version change, no matter
+which type has been used. This will be appended to the changelog and release
+notes as well. To preserve good formatting of these notes, the following format
+is prescribed:
+
+```
+BREAKING CHANGE: <explanation in paragraph format>.
+```
+
+An example of that:
+
+```
+feat(api): remove the API deprecated before 1.4.0
+
+To make the project maintainable, we need to cleanup some deprecated
+API.
+
+The API deprecated after 1.4.0 are not concerned by this cleanup.
+
+BREAKING CHANGE: the old API `foo.bar` was deprecated since version 1.3.4 and is
+removed now.
+
+BREAKING CHANGE: the old API `foo.baz` was deprecated since version 1.2.6 and is
+removed now.
+```
--
GitLab