From 670d534dfaff6307c46c62900270824a37cdb6bb Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Thu, 8 Sep 2022 11:06:46 +0100 Subject: [PATCH 1/8] feat: adding git cliff toml --- Makefile | 4 +++ cliff.toml | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 cliff.toml diff --git a/Makefile b/Makefile index 9311b6b80a6..3a4615bf768 100644 --- a/Makefile +++ b/Makefile @@ -170,6 +170,10 @@ view-docs: @cd docs && \ npm install && npm run serve + +release-notes: + git-cliff --unreleased --tag=$(tag) + .PHONY: build-docs ############################################################################### diff --git a/cliff.toml b/cliff.toml new file mode 100644 index 00000000000..89346dd8d01 --- /dev/null +++ b/cliff.toml @@ -0,0 +1,72 @@ +# configuration file for git-cliff (0.1.0) + +[changelog] +# changelog header +header = """ +# Changelog\n +All notable changes to this project will be documented in this file.\n +""" +# 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 = """ + +""" + +[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}))" }, +] +# 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 = "Dependencies" }, + { message = "^((?i)api-breaking)", group = "API Breaking" }, + { message = "^((?i)state-machine-breaking|(?i)smb)", group = "State Machine Breaking" }, + { message = "^((?i)improvements|(?i)imp)", group = "Improvements" }, + { message = "^((?i)feature|(?i)feat)", group = "Features" }, + { message = "^((?i)fix|(?i)bug)", group = "Bug Fixes" }, + { message = "^((?i)doc|(?i)docs|(?i)documentation)", group = "Documentation" }, + { message = "^((?i)test|(?i)e2e)", group = "Testing" }, + { message = "^((?i)chore|(?i)misc|(?i)nit)", group = "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" From d8cafd4a18de10a616b24e15db8d5d819cb28457 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 7 Nov 2022 13:20:53 +0000 Subject: [PATCH 2/8] chore: using docker image to generate changelog --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 3a4615bf768..b46041120b2 100644 --- a/Makefile +++ b/Makefile @@ -171,8 +171,8 @@ view-docs: npm install && npm run serve -release-notes: - git-cliff --unreleased --tag=$(tag) +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 From 16ee6890bd14372f02f719549bddcd72dba64635 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 7 Nov 2022 14:22:06 +0000 Subject: [PATCH 3/8] chore: adding usage information in cliff.toml --- cliff.toml | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/cliff.toml b/cliff.toml index 89346dd8d01..cabe007f66e 100644 --- a/cliff.toml +++ b/cliff.toml @@ -3,8 +3,34 @@ [changelog] # changelog header header = """ -# Changelog\n -All notable changes to this project will be documented in this file.\n + + +# Changelog +All notable changes to this project will be documented in this file. """ # template for the changelog body # https://tera.netlify.app/docs/#introduction @@ -56,7 +82,8 @@ commit_parsers = [ { message = "^((?i)fix|(?i)bug)", group = "Bug Fixes" }, { message = "^((?i)doc|(?i)docs|(?i)documentation)", group = "Documentation" }, { message = "^((?i)test|(?i)e2e)", group = "Testing" }, - { message = "^((?i)chore|(?i)misc|(?i)nit)", group = "Miscellaneous Tasks" }, + { message = "^((?i)deprecated)", group = "Deprecated" }, + { message = "^((?i)chore|(?i)misc|(?i)nit)", group = "Miscellaneous Tasks" }, ] # filter out the commits that are not matched by commit parsers filter_commits = false From 4569ff094ed198d1cf04b36b6cd5d8083ad651e2 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Fri, 11 Nov 2022 12:14:51 +0000 Subject: [PATCH 4/8] chore: implemnted regex change suggestions --- cliff.toml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/cliff.toml b/cliff.toml index cabe007f66e..8ec3dcdee59 100644 --- a/cliff.toml +++ b/cliff.toml @@ -15,8 +15,6 @@ Each commit should be conventional, the following message groups are supported. * imp * bug, fix * deprecated -* api-breaking -* state-machine-breaking, smb Types of changes (Stanzas): @@ -24,8 +22,8 @@ Types of changes (Stanzas): "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) +"API Breaking" for breaking exported APIs used by developers building on SDK. (prefix commit with ! e.g. !fix: api breaking fix ) +"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. (prefix commit with !!fix: state machine breaking fix ) Ref: https://keepachangelog.com/en/1.0.0/ --> @@ -75,8 +73,8 @@ commit_parsers = [ # 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 = "Dependencies" }, - { message = "^((?i)api-breaking)", group = "API Breaking" }, - { message = "^((?i)state-machine-breaking|(?i)smb)", group = "State Machine Breaking" }, + { message = "^!{!}", group = "API Breaking" }, + { message = "^!{2}", group = "State Machine Breaking" }, { message = "^((?i)improvements|(?i)imp)", group = "Improvements" }, { message = "^((?i)feature|(?i)feat)", group = "Features" }, { message = "^((?i)fix|(?i)bug)", group = "Bug Fixes" }, From aabaed751f33ad93319db352001732669978af39 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Fri, 11 Nov 2022 14:25:23 +0000 Subject: [PATCH 5/8] chore: updating CONTRIBUTING.md with details about commit messages --- CONTRIBUTING.md | 19 +++++++++++++++++++ cliff.toml | 10 ++++++---- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1111fc6d10..aec00b2cc4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,6 +85,25 @@ All PRs require an approval from at least one CODEOWNER before merge. PRs which - If you sat down with the PR submitter and did a pairing review please note that in the `Approval`, or your PR comments. - If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. +### Commit Messages + +Commit messages should be [conventional](https://www.conventionalcommits.org/en/v1.0.0/). + +The commit message type should be one of: + +* `feat` / `feature` for feature work. +* `bug` / `fix` for bug fixes. +* `imp` / `improvements` for improvements. +* `doc` / `docs` / `documentation` for any documentation changes. +* `test` / `e2e` for any tests added. +* `deprecated` for deprecation changes. +* `deps` / `build` for changes to dependencies. +* `chore` / `misc` / `nit` for any miscellaneous changes that don't fit into another category. + +**Note**: If any change breaking, the following format must be used: +* `type` + `(api)!` for api breaking changes, e.g. `fix(api)!: api breaking fix` +* `type` + `(statemachine)!` for state machine breaking changes, e.g. `fix(statemachine)!: state machine breaking fix` + ### Updating Documentation If you open a PR on ibc-go, it is mandatory to update the relevant documentation in /docs. diff --git a/cliff.toml b/cliff.toml index 8ec3dcdee59..c0bce587c3a 100644 --- a/cliff.toml +++ b/cliff.toml @@ -15,6 +15,8 @@ Each commit should be conventional, the following message groups are supported. * imp * bug, fix * deprecated +* (api)! +* (statemachine)! Types of changes (Stanzas): @@ -22,8 +24,8 @@ Types of changes (Stanzas): "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. (prefix commit with ! e.g. !fix: api breaking fix ) -"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. (prefix commit with !!fix: state machine breaking fix ) +"API Breaking" for breaking exported APIs used by developers building on SDK. Add (api)! e.g. fix(api)!: api breaking fix +"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. Add (statemachine)! e.g. fix(statemachine)!: state machine breaking fix Ref: https://keepachangelog.com/en/1.0.0/ --> @@ -73,8 +75,8 @@ commit_parsers = [ # 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 = "Dependencies" }, - { message = "^!{!}", group = "API Breaking" }, - { message = "^!{2}", group = "State Machine Breaking" }, + { message = '^.*\(api\)!', group = "API Breaking" }, + { message = '^.*\(statemachine\)!', group = "State Machine Breaking" }, { message = "^((?i)improvements|(?i)imp)", group = "Improvements" }, { message = "^((?i)feature|(?i)feat)", group = "Features" }, { message = "^((?i)fix|(?i)bug)", group = "Bug Fixes" }, From 2353229dfeeba9eccbd443e6ab04edb5c7fa140f Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 14 Nov 2022 09:34:27 +0000 Subject: [PATCH 6/8] Update CONTRIBUTING.md Co-authored-by: Carlos Rodriguez --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aec00b2cc4e..b4dee078473 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,7 @@ The commit message type should be one of: * `bug` / `fix` for bug fixes. * `imp` / `improvements` for improvements. * `doc` / `docs` / `documentation` for any documentation changes. -* `test` / `e2e` for any tests added. +* `test` / `e2e` for addition or improvements of unit, integration and e2e tests or their corresponding infrastructure. * `deprecated` for deprecation changes. * `deps` / `build` for changes to dependencies. * `chore` / `misc` / `nit` for any miscellaneous changes that don't fit into another category. From d90488e423b0cf47a484a2b2148dd86f786fc2c8 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Mon, 14 Nov 2022 12:35:41 +0000 Subject: [PATCH 7/8] chore: addressing PR feedback and updating pull request template --- .github/PULL_REQUEST_TEMPLATE.md | 35 ++++++++++++++++++++++++++------ CHANGELOG.md | 2 +- CONTRIBUTING.md | 6 +++++- cliff.toml | 2 +- 4 files changed, 36 insertions(+), 9 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4479c1cfc8b..919bd865df6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,18 +12,41 @@ are the most critical to review. closes: #XXXX + +### Commit Message / Changelog entry + +```bash +type: commit message +``` + +see the [guidelines](../CONTRIBUTING.md#commit-messages) for commit messages. (view raw markdown for examples) + + + + --- Before we can merge this PR, please make sure that all the following items have been checked off. If any of the checklist items are not applicable, please leave them but write a little note why. -- [ ] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting)) +- [ ] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting)). - [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work. - [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules/10-structure.md). -- [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing) -- [ ] Updated relevant documentation (`docs/`) or specification (`x//spec/`) +- [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing). +- [ ] Updated relevant documentation (`docs/`) or specification (`x//spec/`). - [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code). -- [ ] Added a relevant changelog entry to the `Unreleased` section in `CHANGELOG.md` -- [ ] Re-reviewed `Files changed` in the Github PR explorer -- [ ] Review `Codecov Report` in the comment section below once CI passes +- [ ] Provide a [commit message](../CONTRIBUTING.md#commit-messages) to be used for the changelog entry in the PR description for review. +- [ ] Re-reviewed `Files changed` in the Github PR explorer. +- [ ] Review `Codecov Report` in the comment section below once CI passes. diff --git a/CHANGELOG.md b/CHANGELOG.md index 76a3cc30065..540e18d9332 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,7 @@ Types of changes (Stanzas): "Bug Fixes" for any bug fixes. "Client Breaking" for breaking CLI commands and REST routes used by end-users. "API Breaking" for breaking exported APIs used by developers building on SDK. -"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. +"State Machine Breaking" for any changes that result in a different AppState given the same genesisState and txList. Ref: https://keepachangelog.com/en/1.0.0/ --> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4dee078473..292a924d06b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,6 +89,8 @@ All PRs require an approval from at least one CODEOWNER before merge. PRs which Commit messages should be [conventional](https://www.conventionalcommits.org/en/v1.0.0/). +If opening a PR, include the proposed commit message in the PR description. + The commit message type should be one of: * `feat` / `feature` for feature work. @@ -100,10 +102,12 @@ The commit message type should be one of: * `deps` / `build` for changes to dependencies. * `chore` / `misc` / `nit` for any miscellaneous changes that don't fit into another category. -**Note**: If any change breaking, the following format must be used: +**Note**: If any change is breaking, the following format must be used: * `type` + `(api)!` for api breaking changes, e.g. `fix(api)!: api breaking fix` * `type` + `(statemachine)!` for state machine breaking changes, e.g. `fix(statemachine)!: state machine breaking fix` +**`api` breaking changes take precedence over `statemachine` breaking changes.** + ### Updating Documentation If you open a PR on ibc-go, it is mandatory to update the relevant documentation in /docs. diff --git a/cliff.toml b/cliff.toml index c0bce587c3a..3a4f68a2729 100644 --- a/cliff.toml +++ b/cliff.toml @@ -25,7 +25,7 @@ Types of changes (Stanzas): "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. Add (api)! e.g. fix(api)!: api breaking fix -"State Machine Breaking" for any changes that result in a different AppState given same genesisState and txList. Add (statemachine)! e.g. fix(statemachine)!: state machine breaking fix +"State Machine Breaking" for any changes that result in a different AppState given the same genesisState and txList. Add (statemachine)! e.g. fix(statemachine)!: state machine breaking fix Ref: https://keepachangelog.com/en/1.0.0/ --> From 3ba101c84042a3dc900791a4ad7b4ae50e9272a3 Mon Sep 17 00:00:00 2001 From: Cian Hatton Date: Tue, 15 Nov 2022 14:16:30 +0000 Subject: [PATCH 8/8] chore: adding support for processing each individual line of the commit message --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- cliff.toml | 22 +++++++++++++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 919bd865df6..c517591a095 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,7 +13,7 @@ are the most critical to review. closes: #XXXX -### Commit Message / Changelog entry +### Commit Message / Changelog Entry ```bash type: commit message diff --git a/cliff.toml b/cliff.toml index 3a4f68a2729..c29518f5bbf 100644 --- a/cliff.toml +++ b/cliff.toml @@ -60,7 +60,7 @@ 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 +split_commits = true # 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 @@ -68,7 +68,27 @@ commit_preprocessors = [ { 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}))" }, + + # the following patterns only exist because "split_commits" is set to true, and we are processesing + # each line of the commit as a separate message. + # these exist to filter out common messages that appear in commit messages that are technically + # conventional, but we do not way to include in the changelog. + { pattern = '^Signed-off-by:.*', replace='' }, + { pattern = '^Co-authored-by:.*', replace='' }, + # don't include references to issues as changelog entries. + { pattern = '^ref:.*', replace='' }, + # exclude CVSS format, CVE can still be included in regular conventinal commits. + { pattern = 'CVSS:.*', replace='' }, + # don't include dependabot auto merge entries. + { pattern = '.*dependabot-automerge-.*', replace='' }, + # don't include statements saying which issue is closed. + { pattern = '^closes:.*', replace='' }, + # remove standalone links in the commit messages. + { pattern = '^https://.*', replace='' }, + # remove lines with html. + { pattern = '^<.*', replace='' }, ] + # regex for parsing and grouping commits commit_parsers = [ # specifying the number in a comment is a workaround to enable ordering of groups.