Conventional Commits (by Vladimir Ryzhak)
Add more sense to commit messages. Bad example of commit messages:
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
- Developer should follow the following commit structure:
<type>(<scope>): <subject>
<body>
<footer>
- Commit MUST have type and subject and MAY contain scope, body and footer.
- Commit message should start from type keyword which shows specific changes to codebase (Examples of type: feat, fix, docs...).
- Commit MAY contain a scope. It shows fragment of code that was changed (Examples of scopes: products, landing, voting...).
- 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.
- 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).
- Commit footer is used for meta information: external links, issue references and other.(Example: fixes issue #10)
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
Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/ecd54e367f2f5c55ba9b3d75b2609117cef2f786
Message old: Migrations reworked
Message new: build: Link contracts with libraries for migrations
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
Commit link: https://github.com/Thetta/Thetta-DAO-Framework/commit/27472c6dad952a01b2e3f9fa574f2f40e58ce4b2
Message old: fix spaces in coments
Message new: style: Fix spaces in comments
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
- 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:
- Install https://github.com/commitizen/cz-cli
- Install https://github.com/leonardoanalista/cz-customizable (used for template with questions in console)
- Install https://github.com/typicode/husky (used for git hooks)
- Install https://github.com/marionebl/commitlint (before each commit commitlint tool will check whether the commit message is written in “conventional commit” standard way)
Do we need scope in commit description? This part of commit message is optional and I don’t see many scopes in Thetta project.
https://www.conventionalcommits.org
It is also quite easy to generate change logs using conventional commits, for example with: https://github.com/conventional-changelog/conventional-changelog