chore(tooling): add commitlint (#18402)

resolves #16645

.commitlintrc.ts

@@ -0,0 +1,26 @@
+import type { UserConfig } from '@commitlint/types';
+import { RuleConfigSeverity } from '@commitlint/types';
+
+const config: UserConfig = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      RuleConfigSeverity.Error,
+      'always',
+      [
+        'chore',
+        'ci',
+        'docs',
+        'enhancement',
+        'feat',
+        'fix',
+        'release',
+        'revert',
+        'security',
+        'test',
+      ],
+    ],
+  },
+};
+
+export default config;

.github/workflows/commitlint.yml

@@ -0,0 +1,28 @@
+name: 'Commitlint'
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+  actions: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - uses: nrwl/nx-set-shas@v3
+      - name: Monorepo install
+        uses: ./.github/actions/yarn-nm-install
+      - name: Validate PR commits with commitlint
+        if: github.event_name == 'pull_request'
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

.husky/commit-msg

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

.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-yarn lint-staged
+npx --no-install lint-staged

CONTRIBUTING.md

@@ -112,6 +112,7 @@ The administration panel should now be available at http://localhost:4000/admin.
 
 - `yarn watch` starts yarn watch in all packages.
 - `yarn build` builds the `strapi-helper-plugin` (use this command when you develop in the administration panel).
+- `yarn commit` runs an interactive commit CLI to help you write a good commit message inline with our git conventions.
 - `yarn setup` installs dependencies.
 - `yarn lint` lints the codebase.
 - `yarn test:clean` removes the coverage reports.
@@ -160,6 +161,51 @@ $ STRAPI_LICENSE=<license> yarn test:api
 
 ---
 
+## Git Conventions
+
+### Commit messages
+
+We use the following convention:
+
+```
+type: subject
+
+body
+```
+
+The goal of this convention is to help us generate changelogs that can be communicated to our users.
+
+#### Type
+
+The types are based on our GitHub label, here are a subset:
+
+- `fix` – When fixing an issue.
+- `chore` – When doing some cleanup, working on tooling, some refactoring. (usually reserved for **internal** work)
+- `doc` – When writing documentation.
+- `feat` – When working on a feature.
+
+You can see the complete list [here](https://github.com/strapi/strapi/blob/1cb6f95889ccaad897759cfa14d2804adeaeb7ee/.commitlintrc.ts#L11).
+
+#### Subject
+
+The subject of a commit should be a summary of what the commit is about. It should not describe what the code is doing:
+
+- `feat: what the feature is`
+- `fix: what the problem is`
+- `chore: what the PR is about`
+- `doc: what is documented`
+
+Examples:
+
+- `feat: introduce document service`
+- `fix: unable to publish documents due to missing permissions`
+- `chore: refactor data-fetching in EditView to use react-query`
+- `doc: document service API reference`
+
+> ⚠️ For a `fix` commit the message should explain what the commit is fixing. Not what the solution is.
+
+---
+
 ## Miscellaneous
 
 ### Repository Organization

package.json

@@ -32,6 +32,7 @@
     "build": "nx run-many --target=build --nx-ignore-cycles",
     "build:ts": "nx run-many --target=build:ts --nx-ignore-cycles",
     "clean": "nx run-many --target=clean --nx-ignore-cycles",
+    "commit": "commit",
     "doc:api": "node scripts/open-api/serve.js",
     "format": "yarn format:code && yarn format:other",
     "format:code": "yarn prettier:code --write",
@@ -76,6 +77,9 @@
     "@babel/core": "^7.20.12",
     "@babel/eslint-parser": "^7.19.1",
     "@babel/preset-react": "7.18.6",
+    "@commitlint/cli": "17.7.2",
+    "@commitlint/config-conventional": "17.7.0",
+    "@commitlint/prompt-cli": "17.7.2",
     "@playwright/test": "1.38.1",
     "@strapi/admin-test-utils": "workspace:*",
     "@strapi/eslint-config": "0.2.0",