7 ‐ About changelog, release notes and hooks

About commits

Convention commit messages

Try as best as possible to apply conventional commits rules. Keep in mind to have your commits well prefixed, and with the issue number between parenthesis at the end, and also if needed the pull request issue number. If your commits embed contributions for other people, do not forget to add them as co-authors. All of you should also comply to DCO.

Your commit message should be prefixed by keywords you can find in the specification:

fix:
feat:
build:
chore:
ci:
docs:
style:
refactor:
perf:
test:

You can add also ! after the keyword to say a breaking change occurs, and also add a scope between parenthesis like:

feat!: breaking change because..
feat(API)!: breaking change in the API because..
feat: add something in the API...

For example, given a commit to fix the issue n°42, the commit should be like:

fix: title of your commit (#42)

Some details about the fix you propose

Co-authored-by: First author firstname and lastname <first author email>
Co-authored-by: Second author firstname and lastname <second author email>

Signed-off-by: First author firstname and lastname <first author email>
Signed-off-by: Second author firstname and lastname <second author email>

Git hooks

You can also, if you want and are used to hooks, add a commit hook locally on your computer to check commit messages before saving them. To do that create first a hook and give to it execution grant:

touch .git/hooks/commit-msg
chmod u+x .git/hooks/commit-msg

Then add the following code in commit-msg:

#!/bin/bash

# Define patterns for commit message prefixes
# All these prefixes must of course match the rules define for commits parsers in some the cliff.toml files
# for CHANGELOG / RELEASE NOTE generation
# See https://www.conventionalcommits.org/en/v1.0.0/
PATTERN_SECTION_ADDED="feat:|chore: add"
PATTERN_SECTION_REMOVED="refactor: remove|refactor: delete|chore: remove|chore: delete"
PATTERN_SECTION_DEPRECATED="refactor\(deprecated\):|chore\(deprecated\)"
PATTERN_SECTION_FIXED="fix:"
PATTERN_SECTION_SECURITY="fix\(security\):"
PATTERN_SECTION_BREAKING="feat!:|chore!:|refactor!:|fix!:"
PATTERN_SECTION_CHANGED="build:|chore:|ci:|docs:|style:|refactor:|perf:|test:"

# All acceptable patterns
COMMIT_PREFIX_PATTERN="^($PATTERN_SECTION_ADDED|$PATTERN_SECTION_REMOVED|$PATTERN_SECTION_DEPRECATED|$PATTERN_SECTION_FIXED|$PATTERN_SECTION_SECURITY|$PATTERN_SECTION_BREAKING|$PATTERN_SECTION_CHANGED)"

INPUT_FILE=$1
COMMIT_MESSAGE=`head -n1 $INPUT_FILE`
if ! [[ "$COMMIT_MESSAGE" =~ $COMMIT_PREFIX_PATTERN ]]; then
    echo "Bad commit message, it must match one of the following patterns:"
    echo -e "\tTo add things............: 'feat:' \t \t  \t 'chore: add'"
    echo -e "\tTo remove things.........: 'refactor: remove' \t \t 'refactor: delete' \t 'chore: remove' \t 'chore: delete'"
    echo -e "\tTo deprecate things......: 'refactor(deprecated)' \t 'chore(deprecated)'"
    echo -e "\tTo fix things............: 'fix:"
    echo -e "\tFor security fixes.......: 'fix(security)'"
    echo -e "\tFor breaking changes.....: 'feat!:' \t 'chore!:' \t 'refactor!:' \t \t 'fix!:'"
    echo -e "\tFor any other changes....: 'build:' \t 'chore:' \t 'ci:' \t \t \t 'docs:' \t \t 'style:' \t 'refactor:' \t 'perf:' \t 'test:'"
    echo "Your commit message: '$COMMIT_MESSAGE'"
    exit 1
fi

exit 0

About release note

We try also to apply keep a changelog, and semantic versioning both with conventional commits.

You can generate a RELEASE_NOTE.md file using your Git history and git cliff tool. Define first a cliff.toml configuration file containing the code below.

# git-cliff ~ configuration file
# https://git-cliff.org/docs/configuration

[changelog]
# changelog header
header = """
# Release Note\n
All notable changes for this version are here and blablabla.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version -%}
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else -%}
    ## [Unreleased]
{% endif -%}
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message | upper_first }} ({{ commit.id }})\
    {% endfor %}
{% endfor %}\n
"""
# remove the leading and trailing whitespace from the templates
trim = true

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for parsing and grouping commits
commit_parsers = [
  { message = "^feat:", group = "🚀 Features" },
  { message = "^fix:", group = "🐛 Fixes" },
  { message = "^doc:", group = "📖 Docs" },
  { message = "^chore:", group = "🧰 Chore" },
  { message = "^refactor:", group = "🧰 Chore" },
  { message = "^style:", group = "🧰 Chore" },
  { message = "^test:", group = "🧰 Chore" },
  { message = "^ci:", group = "🧰 Chore" },
  { message = "^feat!:", group = "💥 Breaking changes" },
  { message = "^fix!:", group = "💥 Breaking changes" },
  { message = "^doc!:", group = "💥 Breaking changes" },
  { message = "^chore!:", group = "💥 Breaking changes" },
  { message = "^refactor!:", group = "💥 Breaking changes" },
  { message = "^style!:", group = "💥 Breaking changes" },
  { message = "^test!:", group = "💥 Breaking changes" },
  { message = "^ci!:", group = "💥 Breaking changes" },
  { message = "^.*", group = "🧰 Chore" },
]
commit_preprocessors = [
    { pattern = '.*', replace_command = 'git show -s --format=%B $COMMIT_SHA' }
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = true
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = "v0.1.0-beta.1"
# regex for ignoring tags
ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"

Then run the following command to build a release note from tag1 to tag2 (or HEAD if tag2 does not exist):

git cliff --config cliff.toml --output RELEASE_NOTE.md tag1..tag2

About changelog

You can use the same tool for CHANGELOG if you want to keep only one CHANGELOG, but this tool is not suitable if several CHANGELOG exist (like one per module). In case you want one CHANGELOG, apply the following .toml file and run git-cliff.

# git-cliff ~ configuration file
# https://git-cliff.org/docs/configuration

[changelog]
# template for the changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version -%}
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else -%}
    ## [Unreleased]
{% endif -%}

{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\n
"""
# template for the changelog footer
footer = """
{% for release in releases -%}
    {% if release.version -%}
        {% if release.previous.version -%}
            [{{ release.version | trim_start_matches(pat="v") }}]: \
                https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
                    /compare/{{ release.previous.version }}..{{ release.version }}
        {% endif -%}
    {% else -%}
        [unreleased]: https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
            /compare/{{ release.previous.version }}..HEAD
    {% endif -%}
{% endfor %}
<!-- generated by git-cliff -->
"""
# remove the leading and trailing whitespace from the templates
trim = true

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for parsing and grouping commits
commit_parsers = [
    { message = "^feat:", group = "Added" },
    { message = "^chore: add", group = "Added" },

    { message = "^refactor: remove", group = "Removed" },
    { message = "^refactor: delete", group = "Removed" },
    { message = "^chore: remove", group = "Removed" },
    { message = "^chore: delete", group = "Removed" },

    { message = "^refactor\\(deprecated\\):", group = "Deprecated" },
    { message = "^chore\\(deprecated\\):", group = "Deprecated" },

    { message = "^fix:", group = "Fixed" },

    { message = "^fix\\(security\\):", group = "Security" },

    { message = "^feat!:", group = "Breaking Change" },
    { message = "^chore!:", group = "Breaking Change" },
    { message = "^refactor!:", group = "Breaking Change" },
    { message = "^fix!:", group = "Breaking Change" },
    
    { message = "^.*", group = "Changed" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = true
# filter out the commits that are not matched by commit parsers
filter_commits = true
# regex for matching git tags
tag_pattern = "v[0-9].*"
# regex for skipping tags
skip_tags = "v0.1.0-beta.1"
# regex for ignoring tags
ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"

Provide feedback

Saved searches