.gitlab-ci.yml

+# -*- coding: utf-8 -*-
+# vim: ft=yaml
+---
+include:
+  - project: EOLE/infra/ci-tools
+    ref: stable
+    file: /templates/Rules.yaml
+  - project: EOLE/infra/ci-tools
+    ref: stable
+    file: /templates/Runners/apps.education-docker.yaml
+  - project: EOLE/infra/ci-tools
+    ref: stable
+    file: /templates/Lint/Commitlint.yaml
+  - project: EOLE/infra/ci-tools
+    ref: stable
+    file: /templates/Release/Semantic-release.yaml
+  - project: EOLE/infra/ci-tools
+    ref: stable
+    file: /templates/Docker.yaml
+
+variables:
+  # `ci-tools` default branch is `stable`
+  STABLE_BRANCH: master
+  IMAGE_NAME: radicale
+
+stages:
+  - initial-checks
+  - build
+  - release
+
+
+###############################################################################
+# `initial-checks` stage: `commitlint`
+###############################################################################
+commitlint:
+  stage: initial-checks
+
+
+###############################################################################
+# `build` stage: `build-docker`
+###############################################################################
+# Build on release tag and every branches except for `$STABLE_BRANCH`
+# used only to create the release tag.
+#
+# The ordering is important:
+# 1. exclude schedules and drafts
+# 2. include `on-release-tag` which must match before `not-on-semantic-release-commit`
+# 3. we exclude stable which just produce the release tag
+# 4. we exclude `semantic-release` commits like when merging `release` on `dev`
+# 5. run on every branches
+build-docker:
+  extends: .build-docker-image
+  variables:
+    KANIKO_ARGS: "--build-arg COMMIT_ID=${CI_COMMIT_SHA}"
+  rules:
+    - !reference [.rules-map, not-on-schedule]
+    - !reference [.rules-map, not-on-draft]
+    - !reference [.rules-map, on-release-tag]
+    - !reference [.rules-map, not-on-stable]
+    - !reference [.rules-map, not-on-semantic-release-commit]
+    - !reference [.rules-map, on-branch]
+
+
+###############################################################################
+# `release` stage: `semantic-release`, `merge-to-dev`, `tag`
+###############################################################################
+# Avoid regression
+merge-to-dev:
+  stage: release
+  extends:
+    - .on-release-tag
+  image: 'hub.eole.education/eole/commitlint:latest'
+  script:
+    # Add `upstream` remote to get access to `upstream/dev`
+    # Use `${GITLAB_TOKEN}` for write permission
+    - "git remote show upstream 2> /dev/null || git remote add upstream ${CI_REPOSITORY_URL/${CI_JOB_TOKEN}/${GITLAB_TOKEN}}"
+    - 'git fetch --all'
+    - 'git checkout -b ${DEV_BRANCH} upstream/${DEV_BRANCH}'
+    - 'git merge --no-edit ${CI_COMMIT_TAG}'
+    - 'git push upstream ${DEV_BRANCH}'
+    # Remove `upstream` to avoid caching `CI_JOB_TOKEN`
+    - "git remote remove upstream"
+
+## tag contribution branches with a more stable name than `git-${CI_COMMIT_SHORT_SHA}`
+tag contrib branch:
+  extends:
+    - .tag-docker-image
+    - .on-branches
+  variables:
+    # `feature/foo-bar_quux` → `feature-foo-bar-quux`
+    IMAGE_TAG: $CI_COMMIT_REF_SLUG
+
+## dev images
+tag dev:
+  extends:
+    - .tag-docker-image
+    - .on-dev
+  variables:
+    IMAGE_TAG: dev
+
+## testing images
+tag testing:
+  extends:
+    - .tag-docker-image
+    - .on-testing
+  variables:
+    IMAGE_TAG: testing
+
+## stable images
+tag release:
+  extends: .tag-docker-image
+
+tag major:
+  extends: .tag-docker-image
+  before_script:
+    - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
+    - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
+    - export IMAGE_TAG=${RELEASE%%.*}
+
+tag minor:
+  extends:
+    - .tag-docker-image
+  before_script:
+    - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
+    - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
+    - export IMAGE_TAG=${RELEASE%.${RELEASE##*.}}
+
+tag stable:
+  extends: .tag-docker-image
+  variables:
+    IMAGE_TAG: stable
+
+tag latest:
+  extends: .tag-docker-image
+  variables:
+    IMAGE_TAG: latest

commitlint.config.js

+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],
+  },
+};

docs/CHANGELOG.md

+# Changelog
+
+## [1.0.1](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/compare/release/1.0.0...release/1.0.1) (2022-01-17)
+
+
+### Continuous Integration
+
+* **build:** create the docker image and push it to `${CI_REGISTRY}` ([a83b538](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/a83b538f58244263ab952fd77f3217f9d4526dae))
+* **commitlint:** enforce commit message format ([a0307fc](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/a0307fcea96614ca6886b37298c681a7b1596745))
+* **release:** avoid regression in `dev` branch ([9d3c342](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/9d3c342c5eb7bc23d51641a5ce388825682bb986))
+* **release:** create release automatically with `semantic-release` ([cf8bf23](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/cf8bf239159eaf5a9f3402ec400e580fc9114555))
+* **release:** tag docker images based on release cycle ([fe406e9](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/fe406e9e95d6f60ef6535bd3b0feb687e418f30a))
+
+
+### Documentation
+
+* **contributing:** explain commit message format ([cfda93f](https://gitlab.mim-libre.fr/alphabet/radicale_laboite/commit/cfda93fc0f545ddbd390aaddf0cafd9a04079b8a))

docs/CONTRIBUTING.md

+# 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.
+
+[[_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.
+```

release-rules.js

+// No release is triggered for the types commented out below.
+// Commits using these types will be incorporated into the next release.
+//
+// NOTE: Any changes here must be reflected in `CONTRIBUTING.md`.
+module.exports = [
+  { breaking: true, release: 'major' },
+  // {type: 'build', release: 'patch'},
+  // {type: 'chore', release: 'patch'},
+  // {type: 'ci', release: 'patch'},
+  { type: 'docs', release: 'patch' },
+  { type: 'feat', release: 'minor' },
+  { type: 'fix', release: 'patch' },
+  { type: 'perf', release: 'patch' },
+  { type: 'refactor', release: 'patch' },
+  { type: 'revert', release: 'patch' },
+  { type: 'style', release: 'patch' },
+  { type: 'test', release: 'patch' },
+];

release.config.js

+// Build the configuration depending of the environnement
+// When using prerelease branches, we don't want changelog to be generated
+// See https://github.com/semantic-release/changelog/issues/51#issuecomment-682609394
+
+// Gitlab reference name
+const branch = process.env.CI_COMMIT_REF_NAME;
+const gitAssets = [];
+
+const config = {
+  branches: 'master',
+  /* eslint no-template-curly-in-string: "off" */
+  tagFormat: 'release/${version}',
+  plugins: [
+    [
+      '@semantic-release/commit-analyzer',
+      {
+        preset: 'angular',
+        releaseRules: './release-rules.js',
+      },
+    ],
+    '@semantic-release/release-notes-generator',
+  ],
+};
+
+if (
+  !Array.isArray(config.branches) ||
+  config.branches.some((it) => it === branch || (it.name === branch && !it.prerelease))
+) {
+  // Generate changelog for release branch
+  config.plugins.push([
+    '@semantic-release/changelog',
+    {
+      changelogFile: 'docs/CHANGELOG.md',
+      changelogTitle: '# Changelog',
+    },
+  ]);
+  gitAssets.push('docs/CHANGELOG.md');
+}
+
+// Commit changes and create release on Gitlab
+config.plugins.push(
+  [
+    '@semantic-release/git',
+    {
+      assets: gitAssets,
+      message: 'chore(release): ${nextRelease.version}\n\n${nextRelease.notes}',
+    },
+  ],
+  '@semantic-release/gitlab',
+);
+
+config.generateNotes = {
+  preset: 'angular',
+  writerOpts: {
+    // Required due to upstream bug preventing all types being displayed.
+    // Bug: https://github.com/conventional-changelog/conventional-changelog/issues/317
+    // Fix: https://github.com/conventional-changelog/conventional-changelog/pull/410
+    /* eslint no-param-reassign: ["error", { "props": true, "ignorePropertyModificationsFor": ["commit", "note"] }] */
+    transform: (commit, context) => {
+      const issues = [];
+
+      commit.notes.forEach((note) => {
+        note.title = `BREAKING CHANGES`;
+      });
+
+      // NOTE: Any changes here must be reflected in `CONTRIBUTING.md`.
+      if (commit.type === `feat`) {
+        commit.type = `Features`;
+      } else if (commit.type === `fix`) {
+        commit.type = `Bug Fixes`;
+      } else if (commit.type === `perf`) {
+        commit.type = `Performance Improvements`;
+      } else if (commit.type === `revert`) {
+        commit.type = `Reverts`;
+      } else if (commit.type === `docs`) {
+        commit.type = `Documentation`;
+      } else if (commit.type === `style`) {
+        commit.type = `Styles`;
+      } else if (commit.type === `refactor`) {
+        commit.type = `Code Refactoring`;
+      } else if (commit.type === `test`) {
+        commit.type = `Tests`;
+      } else if (commit.type === `build`) {
+        commit.type = `Build System`;
+        // } else if (commit.type === `chore`) {
+        //     commit.type = `Maintenance`
+      } else if (commit.type === `ci`) {
+        commit.type = `Continuous Integration`;
+      } else {
+        return null;
+      }
+
+      if (commit.scope === `*`) {
+        commit.scope = ``;
+      }
+
+      if (typeof commit.hash === `string`) {
+        commit.shortHash = commit.hash.substring(0, 7);
+      }
+
+      if (typeof commit.subject === `string`) {
+        let url = context.repository ? `${context.host}/${context.owner}/${context.repository}` : context.repoUrl;
+        if (url) {
+          url = `${url}/issues/`;
+          // Issue URLs.
+          commit.subject = commit.subject.replace(/#([0-9]+)/g, (_, issue) => {
+            issues.push(issue);
+            return `[#${issue}](${url}${issue})`;
+          });
+        }
+        if (context.host) {
+          // User URLs.
+          commit.subject = commit.subject.replace(/\B@([a-z0-9](?:-?[a-z0-9/]){0,38})/g, (_, username) => {
+            if (username.includes('/')) {
+              return `@${username}`;
+            }
+
+            return `[@${username}](${context.host}/${username})`;
+          });
+        }
+      }
+
+      // remove references that already appear in the subject
+      commit.references = commit.references.filter((reference) => {
+        if (issues.indexOf(reference.issue) === -1) {
+          return true;
+        }
+
+        return false;
+      });
+
+      return commit;
+    },
+  },
+};
+
+module.exports = config;