Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add git cliff toml to support generation of changelog #2697

Merged
merged 19 commits into from
Nov 15, 2022
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,10 @@ view-docs:
@cd docs && \
npm install && npm run serve


changelog:
docker run --rm -v "$$(pwd)"/.git:/app/ -v "$$(pwd)/cliff.toml":/app/cliff.toml orhunp/git-cliff:latest --unreleased --tag $(tag)

.PHONY: build-docs

###############################################################################
Expand Down
99 changes: 99 additions & 0 deletions cliff.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# configuration file for git-cliff (0.1.0)

[changelog]
# changelog header
header = """
<!--
Usage:

Change log entries are generated by git cliff ref: https://github.com/orhun/git-cliff
This can be run using "make changelog tag=vx.y.z"

Each commit should be conventional, the following message groups are supported.

* feat, feature
* imp
* bug, fix
* deprecated
* api-breaking
* state-machine-breaking, smb
Copy link
Contributor Author

@chatton chatton Nov 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these are arbitrary and can be decided by us. Note: these strings will not appear in the changelog entry, they are used to group the commits in the changelog.

Copy link
Member

@damiannolan damiannolan Nov 11, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recall some usage of a ! prefix which would indicate an API breaking change.
I'd like to suggest maybe adopting a ! prefix for api breaking changes and !! or something else for state machine breaking.

I feel like its common for us to use squash commits / PR titles similar to:

refactor: some refactor of a module or chore: cleaning up unused to code

But it might be nice to be able to prefix these like:

!refactor: some refactor that breaks an api or !!feat: this feat introduces a state machine breaking change.

Any thoughts on this?


Types of changes (Stanzas):

"Features" for new features. (feat, feature)
"Improvements" for changes in existing functionality. (imp)
"Deprecated" for soon-to-be removed features.
"Bug Fixes" for any bug fixes. (bug, fix)
"API Breaking" for breaking exported APIs used by developers building on SDK. (api-breaking)
"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. (state-machine-breaking, smb)
Ref: https://keepachangelog.com/en/1.0.0/
-->

# Changelog
All notable changes to this project will be documented in this file.
"""
# template for the changelog body
# https://tera.netlify.app/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 | striptags | trim | upper_first }}
{% for commit in commits %}
* {{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}\n
"""
# remove the leading and trailing whitespace from the template
trim = true
# changelog footer
footer = """
<!-- generated by git-cliff -->
"""

[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 preprocessing the commit messages
commit_preprocessors = [
# A reference to an issue is appened to commits that looks like "(#1234)", this will be replaced
# with a link to that issue, e.g. "[#$1234](https://github.com/cosmos/ibc-go/issues/1234)".
{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/cosmos/ibc-go/issues/${2}))" },
# any reference to a pr like "pr-1234" will be replaced with a link to the PR.
{ pattern = '\(pr-([0-9]+)\)', replace = "([#${1}](https://github.com/cosmos/ibc-go/pulls/${1}))" },
]
Copy link
Contributor Author

@chatton chatton Nov 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this effectively means I can write a commit message like

fix: fixed the problem in issue #1234 and also addressed concerns raised in pr-5678

And the issue and pr will be expanded into links in the changelog entry.

e.g.

Bug Fixes

  • fixed the problem in issue #1234 and also addressed concerns raised in #5678

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will the commit merged automatically be linked?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@colin-axner yep the commit being merged will be linked. This is the issue number in parens at the end of the commit in the generated output.

# regex for parsing and grouping commits
commit_parsers = [
# specifying the number in a comment is a workaround to enable ordering of groups.
# these comments are stripped out of the markdown with the filter "{{ group | striptags | trim | upper_first }}"
# above in the body template.
{ message = "^((?i)deps|(?i)dep|(?i)build)", group = "<!-- 0 -->Dependencies" },
{ message = "^((?i)api-breaking)", group = "<!-- 1 -->API Breaking" },
{ message = "^((?i)state-machine-breaking|(?i)smb)", group = "<!-- 2 -->State Machine Breaking" },
{ message = "^((?i)improvements|(?i)imp)", group = "<!-- 3 -->Improvements" },
{ message = "^((?i)feature|(?i)feat)", group = "<!-- 4 -->Features" },
{ message = "^((?i)fix|(?i)bug)", group = "<!-- 5 -->Bug Fixes" },
{ message = "^((?i)doc|(?i)docs|(?i)documentation)", group = "<!-- 6 -->Documentation" },
{ message = "^((?i)test|(?i)e2e)", group = "<!-- 7 -->Testing" },
{ message = "^((?i)deprecated)", group = "<!-- 8 -->Deprecated" },
{ message = "^((?i)chore|(?i)misc|(?i)nit)", group = "<!-- 9 -->Miscellaneous Tasks" },
]
# filter out the commits that are not matched by commit parsers
filter_commits = false
# glob pattern for matching git tags
tag_pattern = "v[0-9]*"
# regex for skipping tags
skip_tags = ""
# regex for ignoring tags
ignore_tags = ""
# sort the tags chronologically
date_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"