# Conventional Commit Messages

A commit message guideline based on the **[Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)**.


## Commit Message Formats

### Default
<pre>
<b><a href="#types">&lt;type&gt;</a></b></font>(<b><a href="#scopes">&lt;optional scope&gt;</a></b>): <b><a href="#description">&lt;description&gt;</a></b>
<sub>empty separator line</sub>
<b><a href="#body">&lt;optional body&gt;</a></b>
<sub>empty separator line</sub>
<b><a href="#footer">&lt;optional footer&gt;</a></b>
</pre>

### Merge Commit
<pre>
Merge branch '<b>&lt;branch name&gt;</b>'
</pre>
<sup>Follows default git merge message</sup>

### Revert Commit
<pre>
Revert "<b>&lt;reverted commit subject line&gt;</b>"
</pre>
<sup>Follows default git revert message</sup>

### Inital Commit 
```
init
```

### Types
* API relevant changes
    * `feat` commits add or remove a new feature
    * `fix` commits fix a bug
* `refactor` commits rewrite/restructure your code but does not change any API behaviour
    * `perf` commits are special `refactor` commits that are specific to performance optimisations
* `style` commits do not affect the meaning of the existing code (whitespace, formatting, missing semi-colons, etc.)
* `test` commits add testing code or correct existing tests
* `docs` commits affect documentation only
* `build` commits affect build components (build tools, ci pipeline, dependencies, project version, etc.)
* `ops` commits affect operational components (infrastructure, deployment, backup, recovery, etc.)
* `chore` commits are miscellaneous commits e.g. modifying `.gitignore`

### Scope (Optional)
The `scope` provides additional contextual information about the commit, such as a one-word description of a section of the codebase (e.g., `fix(parser):`).
* It is an **optional** part of the format
* Allowed scopes depends on the specific project
* Don't use issue identifiers as scopes
* In most cases the scope should be a one-word noun

### Breaking Changes Indicator (Optional)
Breaking changes should be indicated by an `!` before the `:` in the subject line e.g. `feat(api)!: remove status endpoint`
* Is an **optional** part of the format

### Description
The `description` contains a concise description of the change.
* It is a **mandatory** part of the format
* Use the imperative, present tense: "change" not "changed" nor "changes"
  * Think of `This commit will...` or `This commit should...`
* Don't capitalize the first letter
* No period (`.`) at the end

### Body (Optional)
The `body` should include the motivation for the change and contrast this with previous behavior.
* It is an **optional** part of the format
* Use the imperative, present tense: "change" not "changed" nor "changes"
* This is the place to mention issue identifiers and their relations

### Footer (Optional)
The `footer` should contain any information about breaking changes and is also the place to reference issues that this commit refers to.
* It is an **optional** part of the format
* **Optionally** reference an issue by its id.
* **Breaking changes** should start with the word `BREAKING CHANGES:` followed by space or two newlines. The rest of the commit message is then used for this.


### Examples
* ```
  feat: add email notifications on new direct messages
  ```
* ```
  feat(shopping cart): add the amazing button
  ```
* ```
  feat!: remove ticket list endpoint

  refers to JIRA-1337

  BREAKING CHANGES: ticket enpoints no longer supports list all entites.
  ```
* ```
  fix(api): handle empty message in request body
  ```
* ```
  fix(api): fix wrong calculation of request body checksum
  ```
* ```
  fix: add missing parameter to service call

  The error occurred because of <reasons>.
  ```
* ```
  perf: decrease memory footprint for determine uniqe visitors by using HyperLogLog
  ```
* ```
  build: update dependencies
  ```
* ```
  build(release): bump version to 1.0.0
  ```
* ```
  refactor: implement fibonacci number calculation as recursion
  ```
* ```
  style: remove empty line
  ```

---
  
## Git Hook Scripts to ensure commit message header format

### commit-msg Hook (local)
* ensure `node` and `npx` command is installed on your local machine
* create following file in your local repository folder`.git-hooks/commit-msg`
  ```shell
  #!/usr/bin/env sh
  
  commit_message="$1"
  # exit with a non zero exit code incase of an invalid commit message
  
  # use git-conventional-commits, see https://github.com/qoomon/git-conventional-commits
  npx git-conventional-commits commit-msg-hook "$commit_message"
  
  # or verify $commit_message with your own tooling
  # ...
  
  ```
* ⚠ make `.git-hooks/commit-msg` executable (unix: `chmod +x '.git-hooks/commit-msg'`)
* set git hook directory to `.githooks`  `git config core.hooksPath '.git-hooks'`
* commit `.git-hooks` directory if you want to share them with your team, they only need to call the git config command once after cloning the repository

### pre-receive Hook (server side)
* create following file in your repository folder `.git/hooks/pre-receive`
  ```shell
  #!/usr/bin/env bash

  # Pre-receive hook that will block commits with messges that do not follow regex rule

  commit_msg_type_regex='feat|fix|refactor|style|test|docs|build'
  commit_msg_scope_regex='.{1,20}'
  commit_msg_description_regex='.{1,100}'
  commit_msg_regex="^(${commit_msg_type_regex})(\(${commit_msg_scope_regex}\))?: (${commit_msg_description_regex})\$"
  merge_msg_regex="^Merge branch '.+'\$"

  zero_commit="0000000000000000000000000000000000000000"

  # Do not traverse over commits that are already in the repository
  excludeExisting="--not --all"

  error=""
  while read oldrev newrev refname; do
    # branch or tag get deleted
    if [ "$newrev" = "$zero_commit" ]; then
      continue
    fi

    # Check for new branch or tag
    if [ "$oldrev" = "$zero_commit" ]; then
      rev_span=`git rev-list $newrev $excludeExisting`
    else
      rev_span=`git rev-list $oldrev..$newrev $excludeExisting`
    fi

    for commit in $rev_span; do
      commit_msg_header=$(git show -s --format=%s $commit)
      if ! [[ "$commit_msg_header" =~ (${commit_msg_regex})|(${merge_msg_regex}) ]]; then
        echo "$commit" >&2
        echo "ERROR: Invalid commit message format" >&2
        echo "$commit_msg_header" >&2
        error="true"
      fi
    done
  done

  if [ -n "$error" ]; then
    exit 1
  fi
  ```
* ⚠ make `.git/hooks/pre-receive` executable (unix: `chmod +x '.git/hooks/pre-receive'`)

-----
## References
* https://www.conventionalcommits.org/
* https://github.com/angular/angular/blob/master/CONTRIBUTING.md
* http://karma-runner.github.io/1.0/dev/git-commit-msg.html
<br>

* https://github.com/github/platform-samples/tree/master/pre-receive-hooks  
* https://github.community/t5/GitHub-Enterprise-Best-Practices/Using-pre-receive-hooks-in-GitHub-Enterprise/ba-p/13863