Avimitin’s commit convention is a commit style that keep simplicity and semantic version marker.

1. Too long didn’t read

type[.|!] module: summary

[body]

[footer]

Component in [] means optional, other are required.

This is similar to the Conventional Commits 1.0.0, but it trim the long commit type. I don’t want the "refactor(scope)" text or other type text ocupy so much space. Also I want to align all the type. So here is the result.

  • Type "N", stands for new, used when you implement new features.

  • Type "F", stands for fix, used when you fix some unexpected behavior.

  • Type "R", stands for refactor, used when you modify the code.

  • Type "D", stands for document, used when you update code comment, readme, or any other document.

  • Type "M", stands for miscellaneous, used when you update CI workflow, update format file or do any other miscellaneous works.

  • Use "!" instead of "." when you are making breaking changes.

So after this new design, the commit message will be like:

Example
N. socket: implement new API `read()`
R. buffer: rewrite the `write_buf()` function
F. io/net: fix CVE-2021-9999
D. readme: add guideline for using docker build

# breaking change
R! lib/crypto: remove the SHA-1 library support

2. Title

Title is really important. For developer, you can generate change log and semantic version by git log --oneline. For user, they can know if the developer made any important changes. So a proper title helps all the people.

2.1. length

Title should be wrap in 50 Latin characters.

2.2. description

The first word of the title should be lower case and must be a verb. Don’t end with a period and don’t attach any tense on it. You must write the commit in the imperative.

For example:

This is good
refactor subsystem X for readability
update getting started documentation
remove deprecated methods
release version 1.0.0
And this is bad
fixed bug with Y              ==> don't use tense
changing behavior of X        ==> don't use tense
more fixes for broken stuff   ==> use verb to make order
sweet new API methods         ==> there is no verb

A rule of thumb is to fill this sentence: "This patch will modify the project to…​".

Good Example

  • This patch will modify the project to refactor subsystem X for readability

  • This patch will modify the project to update getting started documentation

  • This patch will modify the project to remove deprecated methods

  • This patch will modify the project to release version 1.0.0

So now the none-imperative commit are not working

  • This patch will modify the project to fixed bug with Y

  • This patch will modify the project to changing behavior of X

  • This patch will modify the project to more fixes for broken stuff

  • This patch will modify the project to sweet new API methods

3. Body

3.1. General

Body is optional. You can use any markup language that is well-knowing in the body section. And you should write down what you have done and why you did this. Don’t write about how you do this.

If you are woring on a new PR, remember to attach the issue ID and PR ID.

Also if this commit contains breaking change, remember to attach BREAKING CHANGE: to told what has been change at the end of the body section. See the section "Full Example" for details.

3.2. Recommend format

My daily practice are listed below. It is a mix of markdown, restructure text, and Rust document.

Click to expand! 
Section
=======

You can put text in in *bold*,

You can mark text as code with double backquote `println!()`.

Literal code blocks (ref) are introduced by indented, and, like all paragraphs,
separated from the surrounding ones by blank lines):

This is a normal text paragraph. The next paragraph is a code sample:

  fn main() {
    println!("Hello World");
  }

This is a normal text paragraph again.

List can be nested.

* item 1
* item 2
  * item 2.1
* item 3

You can use Rust way to define a reference link: [GitHub].

[GitHub]: https://github.com/Avimitin/commit-convention

3.3. One Line Per Sentence

Besides, I recommend using one line per sentence. Imaging you are editing a large paragraph, and you find yourself have syntax error at the previous sentences. You remove or add new word, it cause the editing line over 80 characters. So you have to edit the whole paragraph to fit in 80 characters per line.

So as you are using asciidoc format, I recommend you to use one line per sentence. You can read this article to know more benefit you can gain.

4. Footer

Footer should contains all the collaborators’s name and email. If someone mention a bug, attach "Reported-by: Tom <[email protected]>". If someone help you test the code, attach "Tested-by: Sam <[email protected]>".

If you are using GPG to sign your commit, you can attach your name at the end of the rooter like: "Signed-off-by: Yourname <[email protected]>".

5. Full Example

fix! popup/push: fix action push elsewhere

Major fixes
===========

First of all, the push elsewhere action fail to refresh pop up status.
This is because it didn't pass the `popup` variable.

Secondly, the `git.branch.prompt_for_branch()` function needs a list of
branches to test if arguments are contained in options.
But the original code just calls it without any arguments.
So I provide `git.branch.get_all_branches()` to generate necessary
arguments.

Besides, I truncate the unexpected git branch in [commit 12f831669].

BREAKING CHANGE
----------------
* git.branch.get_local_branches is now private

Fixes: #233

Reference
---------
[commit 12f8e1669]: https://github.com/user/project/commit/12f8e166965e8b706d3b54876f92d3e6052f5c84

Signed-off-by: Avimitin <[email protected]>

6. Template usage

You can use my commit template:

git clone https://github.com/Avimitin/commit-convention.git
git config --global commit.template $PWD/commit-convention/template.txt

7. How to generate changelogs

Take a look on my new changelog generator project: https://github.com/Avimitin/changelog_generator

8. Credit

This convention is inspired by the below project:

9. License

CC-BY-4.0

(c) 2021 Avimitin