From 9626bfb32bf0036ecceb98f6565f52a6598e3483 Mon Sep 17 00:00:00 2001
From: Bobby Noelte <b0661n0e17e@gmail.com>
Date: Mon, 7 Apr 2025 22:23:35 +0200
Subject: [PATCH] ci: lint commit messages (#510)

Lint commit messages using gitlint in pre-commit.
Gitlint enforces rules that are configured by .gitlint.

The checks enforce the [`Conventional Commits`](https://www.conventionalcommits.org)
commit message style.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
---
 .gitlint                            | 35 +++++++++++++++++++++++++++++
 .pre-commit-config.yaml             |  6 ++++-
 CONTRIBUTING.md                     | 10 +++++++--
 Makefile                            |  7 +++++-
 requirements-dev.txt                |  2 ++
 scripts/gitlint/eos_commit_rules.py |  1 +
 6 files changed, 57 insertions(+), 4 deletions(-)
 create mode 100644 .gitlint
 create mode 100644 scripts/gitlint/eos_commit_rules.py

diff --git a/.gitlint b/.gitlint
new file mode 100644
index 0000000..ddd882a
--- /dev/null
+++ b/.gitlint
@@ -0,0 +1,35 @@
+[general]
+# verbosity should be a value between 1 and 3, the commandline -v flags take precedence over this
+verbosity = 3
+
+regex-style-search=true
+
+# Ignore rules, reference them by id or name (comma-separated)
+ignore=title-trailing-punctuation, T3
+
+# Enable specific community contributed rules
+contrib=contrib-title-conventional-commits,CC1
+
+# Set the extra-path where gitlint will search for user defined rules
+extra-path=scripts/gitlint
+
+[title-max-length]
+line-length=80
+
+[title-min-length]
+min-length=5
+
+[ignore-by-title]
+# Match commit titles starting with "Release"
+regex=^Release(.*)
+ignore=title-max-length,body-min-length
+
+[ignore-by-body]
+# Match commits message bodies that have a line that contains 'release'
+regex=(.*)release(.*)
+ignore=all
+
+[ignore-by-author-name]
+# Match commits by author name (e.g. ignore dependabot commits)
+regex=dependabot
+ignore=all
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 03024ab..9d1098a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
           - "numpy==2.1.3"
         pass_filenames: false
   - repo: https://github.com/jackdewinter/pymarkdown
-    rev: main
+    rev: v0.9.29
     hooks:
       - id: pymarkdown
         files: ^docs/
@@ -42,3 +42,7 @@ repos:
         args:
           - --config=docs/pymarkdown.json
           - scan
+  - repo: https://github.com/jorisroovers/gitlint
+    rev:  v0.19.1
+    hooks:
+      - id: gitlint
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2a18b54..ecc78ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,8 +21,8 @@ There are just too many possibilities and the project would drown in tickets oth
 ## Code Contributions
 
 We welcome code contributions and bug fixes via [Pull Requests](https://github.com/Akkudoktor-EOS/EOS/pulls).
-To make collaboration easier, we require pull requests to pass code style and unit tests.
-
+To make collaboration easier, we require pull requests to pass code style, unit tests, and commit
+message style checks.
 
 ### Setup development environment
 
@@ -60,6 +60,7 @@ To run formatting automatically before every commit:
 
 ```bash
 pre-commit install
+pre-commit install --hook-type commit-msg
 ```
 
 Or run them manually:
@@ -75,3 +76,8 @@ Use `pytest` to run tests locally:
 ```bash
 python -m pytest -vs --cov src --cov-report term-missing tests/
 ```
+
+### Commit message style
+
+Our commit message checks use [`gitlint`](https://github.com/jorisroovers/gitlint). The checks
+enforce the [`Conventional Commits`](https://www.conventionalcommits.org) commit message style.
diff --git a/Makefile b/Makefile
index bdd2a69..ca33346 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
 # Define the targets
-.PHONY: help venv pip install dist test test-full docker-run docker-build docs read-docs clean format mypy run run-dev
+.PHONY: help venv pip install dist test test-full docker-run docker-build docs read-docs clean format gitlint mypy run run-dev
 
 # Default target
 all: help
@@ -11,6 +11,7 @@ help:
 	@echo "  pip          - Install dependencies from requirements.txt."
 	@echo "  pip-dev      - Install dependencies from requirements-dev.txt."
 	@echo "  format       - Format source code."
+	@echo "  gitlint      - Lint last commit message."
 	@echo "  mypy         - Run mypy."
 	@echo "  install      - Install EOS in editable form (development mode) into virtual environment."
 	@echo "  docker-run   - Run entire setup on docker"
@@ -127,6 +128,10 @@ test-full:
 format:
 	.venv/bin/pre-commit run --all-files
 
+# Target to trigger gitlint using pre-commit for the last commit message
+gitlint:
+	.venv/bin/pre-commit run gitlint --hook-stage commit-msg --commit-msg-filename .git/COMMIT_EDITMSG
+
 # Target to format code.
 mypy:
 	.venv/bin/mypy
diff --git a/requirements-dev.txt b/requirements-dev.txt
index e8cf61a..ac3fc73 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -1,9 +1,11 @@
 -r requirements.txt
+gitlint==0.19.1
 gitpython==3.1.44
 myst-parser==4.0.1
 sphinx==8.2.3
 sphinx_rtd_theme==3.0.2
 sphinx-tabs==3.4.7
+pymarkdownlnt==0.9.29
 pytest==8.3.5
 pytest-cov==6.0.0
 pytest-xprocess==1.0.2
diff --git a/scripts/gitlint/eos_commit_rules.py b/scripts/gitlint/eos_commit_rules.py
new file mode 100644
index 0000000..8928d56
--- /dev/null
+++ b/scripts/gitlint/eos_commit_rules.py
@@ -0,0 +1 @@
+# Placeholder for gitlint user rules (see https://jorisroovers.com/gitlint/latest/rules/user_defined_rules/).