Use conventional commit messages

[2bndy5]

I want to better my git game with proper changelogs (preferably generated from git log). To do this, I need to follow a standard for formatting commit messages, specifically the commit title (not the messages' extra details in the message body).

My research on commit message standards

The most popular standard I've come across is the conventional commit (which evolved from the angular project's guidelines).

There are a bunch of tools to enforce this. Ideally, I want

• a pre-commit hook that only runs on the main branch
• a github action that verifies the PR title (which would be used for merge commits to main)

My research on changelogs

There are A LOT of tools out there that generate changelogs from a project's git history and/or a project's git server data (like github, gitlab, and others). The keep-a-changlog standard is a widely adopted format used for generated a changelog.

For the cpp_linter_rs project, I went with [git-cliff] because it seemed the most flexible. For other cpp-linter repos, we've been using release-drafter to keep a privately drafted release description updated until we're ready to publish. This has been ok, but it has a few problems:

1. release-drafter can be configured to follow keep-a-changelog convention, but it does not generate a changelog. See FAQ in keep-a-changelog site about github releases.
2. release-drafter does not account for simple commits to default branch. It only generates changes from merged PRs.
3. poor support for pre-releases. While release-drafter can be coaxed into bumping to a pre-release version, it requires manual overrides to do so. This may not be important for the entire cpp-linter org, but I noted it because cpp_linter_rs is currently in pre-release status.

Introducing git-cliff

With git-cliff, we can include direct commits main branch and merge commits from PRs.
When told the name of the github repo, git-cliff will fetch PR labels from GitHub's REST API.
The labels can then be used the same as release-drafter interprets them (via cliff.toml configuration rules).

With git-cliff, we can

generate a changelog

git cliff --output CHANGELOG.md

generate a release description for a specific version

git cliff --version v2.0.0

generate a release description for a the next version

Here, we can add the --bump option to auto-increment the version number based on unreleased changes.

git cliff --unreleased --bump

get the next release version based on unreleased changes

git cliff --bumped-version

Tip

If we don't want to auto-bump the version number, we can manually specify the next unreleased tag instead.

git cliff --tag 3.0.0

Additionally, we can annotate the unreleased tag too:

git cliff --tag 3.0.0 --with-tag-message "Some famous quote"

[shenxianpeng]

I have used conventional commit for years, most time I can follow the spec to write commit as conventional commits, but sometimes I just want to try it out, but I still need to think of a good commit message for each commit. So, I mostly like to write a good title for the pull request instead of writing a good commit message for all the commits in the pull request to save energy and disrupt the thinking of writing code. that is way of release-drafte did. (By the way I created conventional branch recently).

There are bunch of tools but I feel they don't suite me, so I created @commit-check.

• commit-check can be used as pre-commit hooks
• commit-check-action works as a github action

I know commit-check may not work perfect, but worth to try and appreciate to get real users's feedback to help improve it.

---

release-drafter can be configured to follow keep-a-changelog convention, but it does not generate a changelog. See FAQ in keep-a-changelog site about github releases.

indeed. maybe for cpp_linter_rs can customize their release-drafter.yml to include a link to the changelog, such as https://cpp-linter.github.io/cpp_linter_rs/CHANGELOG.html, similar to how the Jenkins project handles it: https://github.com/jenkinsci/jenkins/releases. Personally I perfer to take a look the GitHub release tab to see the diff changes and release notes insead to go to code base to find the CHANGELOG.md.

release-drafter does not account for simple commits to default branch. It only generates changes from merged PRs.

indeed. it shoud not friendly for projects that have just started and have a lot of changes, but for projects that have been officially released, only make change through PR has its advantages, including modified code, comments, etc., and it can avoid mistakes.

For individual project, it can be used the best way they would. For organizational projects, maintaining a consistent approach across the board is usually beneficial unless it really doesn't fit.

[shenxianpeng]

@coderabbitai works great. I even felt a little bit like I was useless. It seems that the trial period has passed and code review is no longer supported.

[shenxianpeng]

It would be my pleasure to invite you if you are also interested in commit-check. Anyway I know you have many things to do and bandwidth may not be enough.

[2bndy5]

It is subject to REST API rate limits. If the review fails, then there will be a message stating how long to wait for the limit to reset.

I also configured it to not review bot-generated PRs.

[shenxianpeng]

I have seen some people using conventional branch names. I did it once and the / caused some problems with git checkout

We've used conventional branch names integrated with Jenkins for years without encountering this issue, so it might be specific to GitHub Aciton with the git checkout command.

[2bndy5]

no I mean on the command line. Using tab completion doesn't automatically add the needed quotes around branches that look like paths.

[2bndy5]

Unreleased changes are good for project developers, but not for outsiders looking to see what changes they're using in production. Going forward I don't intend to keep the changelog updated with "Unreleased" changes. Instead the Unreleased changes can be viewed from the bump-n-release CI's step summary.