ci(github): better developer experience when committing changes (#1285)

Commitlint and Husky should make it easier for contributors to Serenity/JS to create commit messages
that follow the Conventional Commits format, which will then help to get pull requests merged
quicker.

Additionally, a new check added on GitHub will ensure that the commit format is valid
and  parseable by Semantic Release.

Related tickets: re #1183

.commitlintrc.js

@@ -0,0 +1,13 @@
+const { scopes } = require('./.cz-allowed-scopes');
+
+module.exports = {
+    extends: [
+        '@commitlint/config-conventional'
+    ],
+    rules: {
+        'type-case':    [ 2, 'always', 'lower-case' ],
+        'scope-empty':  [ 2, 'never'                ],
+        'scope-case':   [ 2, 'always', 'lower-case' ],
+        'scope-enum':   [ 2, 'always', scopes.all() ]        
+    }
+}

.cz-allowed-scopes.js

@@ -0,0 +1,56 @@
+const { sync: glob } = require('fast-glob');
+const { readFileSync } = require('fs');
+const path = require('path');
+
+const input = [ path.join(path.resolve(__dirname, `packages`),  `*/package.json`) ];
+const paths = glob(input, { onlyFiles: false, globstar: true, absolute: true });
+
+const serenityPackages = paths.map(pathToPackageJson => path.basename(path.dirname(pathToPackageJson)));
+
+module.exports.scopes = {
+    serenityPackages() {
+        return serenityPackages;
+    },
+    documentation() {
+        return [
+            'examples',
+            'website',
+        ];
+    },
+    dependencies() {
+        return [
+            // Changes to runtime dependencies
+            'deps',
+            // Changes to development-time dependencies
+            'deps-dev',
+        ];
+    },
+    ci() {
+        return [
+            // Configuration changes to "big" CI/CD tools that affect the whole project
+            'github',
+            'gitpod',
+            'lerna',
+            'renovate',
+            'saucelabs',
+            'codeclimate',
+            'codefactor',
+            'eslint',
+        ];
+    },
+    reservedForAutomatedCommits() {
+        return [
+            // Reserved for semantic release
+            'release',
+        ]
+    },
+    all() {
+        return [
+            ...this.serenityPackages(),
+            ...this.documentation(),
+            ...this.dependencies(),
+            ...this.ci(),
+            ...this.reservedForAutomatedCommits()
+        ]
+    }
+}

.cz-config.js

@@ -0,0 +1,49 @@
+const { scopes } = require('./.cz-allowed-scopes');
+
+module.exports = {
+    types: [
+        { value: 'feat',      name: 'feat:     A new feature that will be available to the developers using Serenity/JS, e.g. a new public API' },
+        { value: 'fix',       name: 'fix:      A bug fix, prepared typically to address a specific GitHub ticket' },
+        { value: 'docs',      name: 'docs:     Documentation only changes affecting the website, examples, or the API docs' },
+        { value: 'style',     name: 'style:    Changes that do not affect the meaning of the code, e.g. formatting, fixing missing semicolons, etc.' },
+        { value: 'refactor',  name: 'refactor: Improvements to code that do not affect the observable behaviour of Serenity/JS' },
+        { value: 'perf',      name: 'perf:     A code change aimed at improving performance' },
+        { value: 'test',      name: 'test:     Improvements to existing internal tests, or adding missing tests' },
+        { value: 'revert',    name: 'revert:   Revert to a commit' },
+        { value: 'ci',        name: 'ci:       Changes affecting the tools used in our CI/CD pipeline: e.g. build scripts, GitHub Actions, Gitpod, ESLint, etc.' },
+        { value: 'chore',     name: `chore:    Other changes that don't modify src or test files, e.g. updates to dependencies` },
+    ],
+
+    // scopes:         scopes.all().map(name => ({ name })),
+    scopeOverrides: {
+        'feat':     [ ...scopes.serenityPackages() ],
+        'fix':      [ ...scopes.serenityPackages() ],
+        'docs':     [ ...scopes.serenityPackages(), scopes.documentation() ],
+        'style':    [ ...scopes.all() ],
+        'refactor': [ ...scopes.serenityPackages() ],
+        'perf':     [ ...scopes.serenityPackages() ],
+        'test':     [ ...scopes.serenityPackages() ],
+        'revert':   [ ...scopes.all() ],
+        'ci':       [ ...scopes.ci() ],
+        'chore':    [ ...scopes.all() ],
+    },
+
+    messages: {
+      type:     "Select the TYPE of change you're proposing:",
+      scope:    '\nDenote the SCOPE of this change:', // so that we know what needs to be released?
+      // used if allowCustomScopes is true
+      customScope: 'Denote the SCOPE of this change:',
+      subject:  'WHAT did you change? Please write a SHORT, IMPERATIVE tense description of the change:\n',
+      body:     'WHY did you change it? Provide a LONGER description of the motivation behind the change (optional). Use "|" to break new line\n',
+      breaking: 'List any BREAKING CHANGES, e.g. any public APIs (optional):\n',
+      footer:   'List any GitHub TICKETS affected by this change (optional). E.g.: #31, #34:\n',
+      confirmCommit: 'Are you sure you want to proceed with the commit above?',
+    },
+
+    allowCustomScopes: false,
+    allowBreakingChanges: ['feat', 'fix'],
+
+    // limit subject length
+    subjectLimit: 100,
+    footerPrefix : 'Related tickets:'
+}

.github/workflows/main.yaml

@@ -31,11 +31,15 @@ jobs:
         integration/**
         *
       files-ignore: |
-        .github/workflows/chore*.yaml
+        .github/workflows/chore-*.yaml
+        .github/workflows/pr-*.yaml
         .gitpod/**
-        .gitpod
+        .gitpod.yml
+        .husky/**
         documentation/**
         *.md
+        .commitlintrc.js
+        .cz-*.js
         package-lock.json
 
   lint:

.github/workflows/pr-commitlint.yaml

@@ -0,0 +1,20 @@
+name: Commit message linter
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [ opened, synchronize ]
+
+permissions:
+  contents: read
+
+jobs:
+  check-commit-messages:
+    name: Check commit message format
+    uses: 'serenity-js/serenity-js/.github/workflows/main-node-step.yaml@main'
+    with:
+      fetch-depth: 0
+      node-version: 16.x
+      npm-install-command: npm ci
+      command: |
+        npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose >> $GITHUB_STEP_SUMMARY

.gitpod.yml

@@ -8,9 +8,9 @@ ports:
 
 tasks:
   - name: 'Install Node modules and compile Serenity/JS'
-    env:
-      CHROMEDRIVER_FILEPATH: /usr/lib/chromium-browser/chromedriver
     init: |
+        nvm install
+        nvm use
         make install compile
 
   - name: 'Install VSCode Extensions'
@@ -44,5 +44,5 @@ github:
     pullRequests: true
     pullRequestsFromForks: true
     addCheck: prevent-merge-on-error
-    addComment: false
-    addBadge: true
+    addComment: true
+    addBadge: false

.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit "${1}"