Allow scope declarations in structured commit messages (#512)

* git, doc: document new optional scope and much more readable regex in commit-msg

* feat(commit-msg): print out message even if it is invalid

* feat(commit-msg): print commit message even if it is incorrect

* doc: refer to the contributin md instead of just printing the regex if the git commit message is wrong

* refactor(commit-msg): slightly reformat output

* refactor(commit-msg): remove the `log` type

* doc(contributing): document new scopes for commit messages

.githooks/commit-msg

@@ -4,9 +4,19 @@ message_file="$1"
 message=$(cat "$message_file")
 
 # Define the regular expression pattern
-regex="^((\[(no|skip) ci\] )?(((feat|tests?|lint|refactor|ci|git|special|doc|typo|log|ts|fix|wip|docker|dep)(-fix|-fail)?(, ?)?)+: |Merge (remote-tracking )?branch|Auto-merging).+|\[release:(patch|minor|major)\] .+)"
+regex="^((\[(no|skip) ci\] )?"                                                                  # allow to skip ci steps if required
+regex="$regex(Merge (remote-tracking )?branch|Auto-merging|"                                    # allow merge commit messages
+  regex="$regex("                                                                               # allow multiple types
+    regex="$regex(feat|tests?|lint|refactor|ci|git|special|doc|typo|ts|fix|wip|docker|dep)"     # all valid types
+    regex="$regex(-fix|-fail)?"                                                                 # optional fail suffix
+    regex="$regex(\([^)]+\))?"                                                                  # optional scope
+    regex="$regex(, ?)?"                                                                        # optional comma between types
+  regex="$regex)+: "                                                                            # at least one type is required
+regex="$regex)"                                                                                 # allow arbitrary message (no end marker)
+regex="$regex|\[release:(patch|minor|major)\] .+)"                                              # alternatively, allow release commits (only to be done on main)
 
 if ! echo "$message" | grep -qE "$regex"; then
-  echo "[POLICY] Your message is not formatted correctly. Respect the regex: '$regex'!"
+  echo   "[POLICY] Your message is not formatted correctly. Please respect the style defined in '.github/CONTRIBUTING.md'."
+  printf "[POLICY] Your message was (ignoring git comments):\n\n%s\n" "$(echo "$message" | grep -vE "^#")"
   exit 1
 fi

.github/CONTRIBUTING.md

@@ -33,8 +33,8 @@ If you have any questions, refer to the [wiki](https://github.com/Code-Inspect/f
 
 ## Commit Messages
 
-We structure our commit messages (enforced by our git-hooks) using the format `<type(s)>: <description>`.
-Currently, the following types are at your disposal (more may have been or are still available, but please restrict yourself to the following):
+We structure our commit messages (enforced by our git-hooks) using the format `<type(s)>(<scope>): <description>` (with `(<scope>)` being optional).
+Currently, the following `<type(s)>` are at your disposal (more may have been or are still available, but please restrict yourself to the following):
 
 
 | name                                            | description                                                                                        |
@@ -49,7 +49,6 @@ Currently, the following types are at your disposal (more may have been or are s
 | `lint`                                          | Adapted or updated linter-issues.                                                                  |
 | `doc`                                           | Updated the documentation of *flowR*.                                                              |
 | `typo`                                          | Dealt with a small typo/a grammatical mistake.                                                     |
-| `log`                                           | Improved or updated the logging of *flowR*.                                                        |
 | `ts`                                            | Performed something typescript-specific (e.g., reconfigured the `tsconfig.json`).                  |
 | `wip`                                           | *Use this only in combination with another type*. It marks the commit to be unfinished.            |
 | `special`                                       | *Use this only if none of the other categories apply*. Explain the details in your commit message. |
@@ -65,9 +64,12 @@ Although you can give the same type repeatedly - if you think you should, please
 
 With this, the artificial message
 
-> `feat, test-fix: Support for branching in dataflow, fixed branching-test`
+> `feat, test-fix: Support for branching in dataflow, fixed branching test`
 
 represents the addition of a new feature and the fix of a corresponding test.
+With scopes, it could look like this:
+
+> `feat, test-fix(dataflow): Support branching & fixed branching test`
 
 To skip the `ci`, you can prefix the commit message with `[skip ci]`.