automatic commit message linting

.pre-commit-config.yaml

@@ -6,14 +6,19 @@
 # the 3-Clause BSD License.  See the LICENSE file in the package base
 # directory for details.
 
+# pre-commit checks are defined in this file
+# See https://pre-commit.com for more information
+
+
+default_install_hook_types: [pre-commit, commit-msg]
+
 default_language_version:
     python: python3
     # python >= 3.8 should be used.
     # python3 used for compatibility reasons between different systems
 
 
-# See https://pre-commit.com for more information
-# See https://pre-commit.com/hooks.html for more hooks
+# standard hooks -- more info: https://pre-commit.com/hooks.html
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
@@ -25,28 +30,49 @@ repos:
   - id: check-merge-conflict  # check for merge conflict strings
 
 
-# more info: https://github.com/pre-commit/mirrors-mypy
+# mypy -- more info: https://github.com/pre-commit/mirrors-mypy
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: 'v1.5.1'  # Use the sha / tag you want to point at
   hooks:
-    - id: mypy                  # run mypy
+    - id: mypy
       args: [--config-file=mypy.ini, --ignore-missing-imports]
       #additional_dependencies: [dep==version.version.version, ...]
       # NOTE: pre-commit runs mypy in a virtualenv, so dependencies are not installed unless explicitly listed here
 
-# Using this mirror lets us use mypyc-compiled black, which is about 2x faster
-# more info: https://github.com/psf/black/blob/main/docs/integrations/source_version_control.md
+
+# black -- more info: https://github.com/psf/black/blob/main/docs/integrations/source_version_control.md
 - repo: https://github.com/psf/black-pre-commit-mirror
-  rev: 23.7.0
+  rev: 23.9.1
   hooks:
-  - id: black                  # run black fromatter on all files
+  - id: black
     args: [--line-length=120]
 
 
+# check for discopop license tag
 - repo: local
   hooks:
   - id: licensetag
     name: Check all files for DiscoPoP License tag
     entry: scripts/dev/check-license.sh
     language: script
     # exclude: we could exclude files here, but we do it in the script instead
+
+
+# lint commit messages -- idea based on: https://www.conventionalcommits.org/en/v1.0.0/
+- repo: local
+  hooks:
+  - id: check-commit-msg
+    name: Check commit message
+    entry: python scripts/dev/check-commit-msg.py
+    language: python
+    stages: [commit-msg]
+
+
+# currently we use a custom script for commit message lintining because commitlint did not work consistently on all devices
+#- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+#  rev: v9.5.0
+#  hooks:
+#  - id: commitlint
+#    name: Check commit message with commitlint
+#    stages: [commit-msg]
+#    additional_dependencies: ['@commitlint/config-conventional']

commitlint.config.js

@@ -0,0 +1,11 @@
+/* This file is part of the DiscoPoP software (http://www.discopop.tu-darmstadt.de)
+ *
+ * Copyright (c) 2020, Technische Universitaet Darmstadt, Germany
+ *
+ * This software may be modified and distributed under the terms of
+ * the 3-Clause BSD License.  See the LICENSE file in the package base
+ * directory for details.
+ */
+
+// currently we use a custom script for lintining because commitlint did not work consistently on all devices
+module.exports = { extends: ['@commitlint/config-conventional'] };

docs/How_to_contribute.md

@@ -29,19 +29,15 @@ In general it is sufficient to follow the general installation instructions. How
  - Install the python programs in development mode by executing `pip install -e .[dev]` from the project main directory
    - The `-e` switch ensures that changes in the python source code are immediately active.
    - `[dev]` also installs some development requirements (e.g. mypy, black, pre-commit).
- - Install some git hooks by running `pre-commit install` from the main directory of this project. These hooks help to ensure a good quality of the commited code by automatically running the black **formatter** and checking for **type safety** with mypy on every commit.
- - Activate the git `commit-msg` hook to validate commit message formatting by creating a file named `.git/hooks/commit-msg` with the following contents:
-    ```
-    #!/bin/sh
-    python scripts/dev/check-commit-msg.py $1
-    ```
+ - Install some git hooks by running `pre-commit install` from the main directory of this project. These hooks help to ensure a good quality of the commited code by automatically running some checks:
+   - black is run to **format** python source code
+   - python **type safety** is improved with mypy
+   - we enforce [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+   - other checks like looking for unneccesary whitespace and preventing large files to be added
+
 
 ## Commit messages
-Commit messages should follow the following format:
-```
-<type>(scope)[optional info]: commit message
-```
-where `<type>` can be any of `feat,fix,test,chore,wip`.
+Commit messages should follow the conventional commits format: [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
 
 ## Creating a new release
 Execute the following steps in order to create a new DiscoPoP release:

scripts/dev/check-commit-msg.py

@@ -20,7 +20,7 @@
     commit_msg = f.read()
     commit_msg = commit_msg.replace("\n", "")
 
-pattern = re.compile("^(feat|fix|test|chore|wip)(\(.+\))?(\[.+\])?:.+$")
+pattern = re.compile("^(feat|fix|test|chore|refactor|doc|docs|perf|ci|build|style)(\(.+\))?(\[.+\])?:.+$")
 matches = bool(pattern.match(commit_msg))
 
 if matches:
@@ -31,5 +31,5 @@
     print("\t", commit_msg)
     print("Please use the following format:")
     print("\t<type>(scope)[optional info]: commit message")
-    print("where `<type>` can be any of `feat,fix,test,chore,wip`.")
+    print("where `<type>` can be any of `feat,fix,test,chore,wip,refactor,doc,docs,perf,ci,build,style`.")
     sys.exit(1)