Conventional commits

[hairyhum]

Conventional Commits:

Currently there is no rules about commit messages in this repo, while some people are using
conventional commits approach https://www.conventionalcommits.org/en/v1.0.0/

This proposal is to establish a convention for commit messages to keep them more organized.

The goal here is to help maintainers to navigate commits and help developers to write better
commit messages.

There is no goal to generate changelogs from the commit messages (at the moment).

Base format:

<type>(<optional scope>): <description>
empty separator line
<optional body>
empty separator line
<optional footer>

Types:

• feat - new feature/functionality
  it's recommended to link a GH issue or discussion which describes the feature request
  or describe it in the commit message
• fix - bugfix
  it's recommended to link a GH issue or discussion to describe the bug
  or describe it in the commit message
• refactor - code restructure/refactor which does not affect the (public) behaviour
• style - formatting, adding newlines, etc. in code
  • can be merged with refactor type
• docs - changes in documentation
• test - adding, improving, removing tests
• build - changes to build scripts, dockerfiles, ci pipelines
• deps - updates to dependencies configuration
  • currently used by dependabot
  • can be merged with build type
• chore - none of the above
  use in generally discuraged
• revert - revert previous commit

We can add more types for example if we see a lot of chore type usage.

Scopes:

Scope is optional and used in tools like dependabot,
there is no strict set of scopes but here are some examples:

• build(ci) - changes in github workflow
• deps(go) - dependabot updating go library
• docs(examples) - changes in examples
• feat(kanctl) - new functionality for kanctl (e.g. new command)

Breaking changes indicator:

You can use ! after the type and scope to indicate breaking changes

fix(scope)!: fix with breaking changes

Description:

Short description of WHAT was changed in the commit.
SHOULD start with lowercase.
MUST NOT have a . at the end.

Body:

Body should contain a description of changes and importantly reasoning
behind the changes, it may include links to issues or discussions, but should
be sufficient to understand WHY the commit is there.

May also contain some information about WHAT was changes if description did not fit all of it.

Footer:

In order to indicate breaking changes in the commit message you can use
BREAKING CHANGES: footer, listing breaking changes, e.g.

fix!: here's some fix

fixing something

BREAKING CHANGES: it breaks some thing
and another thing

Tools for validation:

Here are some tools which can be used to validate if commit format matches the spec:

• https://github.com/conventional-changelog/commitlint
• https://github.com/qoomon/git-conventional-commits

Both can be configured with specific types and scopes
Both can be set up to run on pre-commit hooks

There are some others as well out there.

Flow

We can install one of the tools in the build image and run hooks using docker
to avoid install requirements.

How it could work is:

• There is a tool in docker build image
• There is a make commitlint command which runs the tool for HEAD commit (or on the parameter)
• Developers can set up commit-msg hook or post-commit hook (provided instructions) to run the commit lint when committing

On github side:

• There is a non-blocking (warning) job in the PR workflow checking if commits match the convention

[mlavi]

Thanks for the write up, I am in favor of this!

[viveksinghggits]

PR titles should have type and scope and details about breaking change. This PR title should be the commit message when the PR gets merged to master (it's already this way).
But we think having these things in commit message is not going to be that helpful. Commit messages can have the body though. And we can create a new rules/guide on how to format write good commit messages.

[hairyhum]

Do we currently check for PR titles to match a convention?
If we do that and then all commits in master will follow the convention since they're all merged the same way from PRs.

In that case:

• Scopes and types from the above are still relevant.
• PR reviewer MUST rename the PRs before approval to match the convention
• CON: We don't control the footer and breaking changes SHOULD be communicated in the header (PR title)
• CON: We can't validate the commit message because it happens on github

[hairyhum]

Here's a simplified version of types and scopes:

Types:

• feat - new feature/functionality
  it's recommended to link a GH issue or discussion which describes the feature request or describe it in the commit message
• fix - bugfix
  it's recommended to link a GH issue or discussion to describe the bug or describe it in the commit message
• refactor - code restructure/refactor which does not affect the (public) behaviour
• docs - changes in documentation
• test - adding, improving, removing tests
• build - changes to build scripts, dockerfiles, ci pipelines
• deps - updates to dependencies configuration
• chore - none of the above
  use is generally discuraged
• revert - revert previous commit

Scopes:

There is no strict list of scopes to be used, suggested scopes are:

• build(ci) - changes in github workflows
• build(release) - changes in release process
• deps(go) - dependabot updating go library
• docs(examples) - changes in examples
• docs(readme) - changes in MD files at the repo root
• feat(kanctl) - new functionality for kanctl (e.g. new command)
• refactor(style) - formatting, adding newlines, etc. in code

[hairyhum]

#2645 - documenting convention in contributing docs