52 ‐ 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 commit hook for conventional commit message.

Note

Please refer to the DEVELOP dedicated section.

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.

Tip

A template is available in the repo.

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

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

For example to build a release note between version 0.14.0 (tag 0.4.0) and HEAD

git-cliff --config .github/cliff.toml --output RELEASE_NOTE.md 0.14.0..HEAD

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"