Skip to content

Conventional Commits (by Vladimir Ryzhak)

Jump to bottom
Anthony Akentiev edited this page Jan 8, 2019 · 1 revision

Motivation

Add more sense to commit messages. Bad example of commit messages:

Basics

Example

Example commit message using conventional commit standard:

fix(voting): Fix user voting bug

Fix bug when user can vote after voting is finished

Fixes issue #14

Theory

  1. Developer should follow the following commit structure:
<type>(<scope>): <subject>

<body>

<footer>
  1. Commit MUST have type and subject and MAY contain scope, body and footer.
  2. Commit message should start from type keyword which shows specific changes to codebase (Examples of type: feat, fix, docs...).
  3. Commit MAY contain a scope. It shows fragment of code that was changed (Examples of scopes: products, landing, voting...).
  4. Commit subject goes after type and scope.
  • Subject is a short description of the code changes.
  • Subject is written in IMPERATIVE mood as if you tell the codebase what it should do.
  • Subject should not be ended with punctuation mark.
  • Subject length should be <=72 characters.
  • To create a proper subject you may use “If applied, this commit will” technique. So for example you updated a README file. So the subject will be “update README”, NOT “updated README”. Compare 2 sentences: If applied, this commit will update README vs If applied, this commit will updated README.
  • Example: fix: Revert tx when user has already voted.
  1. Commit body is used for detailed description. You should explain what and why was changed. Most of the time you can omit body because code is self explanatory but when changes are complex then it is better to write a good comment. (Example: Revert voting transaction when user is trying to vote 2nd time in the same voting because users can vote only once per voting).
  2. Commit footer is used for meta information: external links, issue references and other.(Example: fixes issue #10)

Commit types

build - Project build and external dependencies

chore - Changes to the build process or auxiliary tools and libraries such as documentation generation

ci - CI/CD setting changes and script changes

docs - Documentation update

feat - Adding new feature

fix - Bug fixing

perf - Changes to increase performance

refactor - Code changes without bug fixes or adding new features

revert - Rollback to previous commits

style - Code style changes(tabs, spaces, dots, etc...)

test - Adding tests

Examples

Example #1

Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/ecd54e367f2f5c55ba9b3d75b2609117cef2f786

Message old: Migrations reworked

Message new: build: Link contracts with libraries for migrations

Example #2 (good one)

Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/5d143cea40380ef5134f350b6205f8606dedcf67

Message old: fix: Voting not included in migration

Message new: fix: Voting not included in migration

Example #3

Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/27472c6dad952a01b2e3f9fa574f2f40e58ce4b2

Message old: fix spaces in coments

Message new: style: Fix spaces in comments

Example #4

Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/5f9b6bc9b6ab190a56387c1d31e867d886de3900

Message old: add unit tests for dao_base

Message new: test: Add unit tests for dao_base

What should be done to apply it to your project?

  1. You may check this video(~1 min) https://asciinema.org/a/212473 to see how it would work. So what should be done to apply conventional commits:
  2. Install https://github.com/commitizen/cz-cli
  3. Install https://github.com/leonardoanalista/cz-customizable (used for template with questions in console)
  4. Install https://github.com/typicode/husky (used for git hooks)
  5. Install https://github.com/marionebl/commitlint (before each commit commitlint tool will check whether the commit message is written in “conventional commit” standard way)

Questions

Do we need scope in commit description? This part of commit message is optional and I don’t see many scopes in Thetta project.

Links

https://www.conventionalcommits.org

Notice

It is also quite easy to generate change logs using conventional commits, for example with: https://github.com/conventional-changelog/conventional-changelog

Clone this wiki locally