diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a74ef9af913..39c869a2dda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,17 +89,76 @@ to make reviews and retrospection easy. Use your git commits to provide context for the reviewers, and the folks who will be reading the codebase in the months and years to come. -Finalized commit messages should look similar to the following format: +Kanister recommends using [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) format: ```text -Short one line title +[optional scope]: -An explanation of the problem, providing context, and why the change is being -made. +[optional body] + +[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 +- `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 + +#### Breaking changes indicator: + +There can be optional `!` 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(optional): + +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 ``` ### Submitting Pull Requests +**Pull request title should follow [conventional commits](#commit-messages) format** + When submitting a pull request, it's important that you communicate your intent, by clearly: