commitizen-tools: What can we gain from crafting a git message convention @ Taipey.py

https://www.meetup.com/Taipei-py/events/271185591/

ⓞⓞⓞ 講題 ⓞⓞⓞ

commitizen-tools: What can we gain from crafting a git message convention?

Bringing great commit conventions helps teams communicate and guides them on how code changes should be made. It saves reviews' time to understand the intention of each pull/merge request, and makes newcomers get into an existing project faster. Besides better communication, formatted commit messages also make parsing them for other uses possible. Trivial stuff like bumping version for your projects or generating changelogs will no longer be your headache!

ⓞⓞⓞ 講師 ⓞⓞⓞ
Wei Lee

Wei Lee is a software engineer at Rakuten Slice, and now also a volunteer of PyCon TW. Being a lazy engineer, he is passionate about automating anything. Mainly use Python for automating trivial stuff, backend development, and maybe building some data pipelines. Love traveling, use PyCon as an excuse to explore the world 😎. Have been to PyCon TW 🇹🇼, PyCon US 🇺🇸, PyCon JP 🇯🇵, PyCon CA 🇨🇦, Remote Python Pizza 🍕.

Personal Website: https://lee-w.github.io/
Twitter: @clleew

Transcript

1. @clleew commitizen-tools What can we gain from crafting a git message convention?
2. @clleew 2019/10/24 - Taipei.py
3. @clleew 2019/10/24 - Taipei.py
4. @clleew
5. @clleew Slide
6. @clleew $ cat speaker.py __name__ = "Wei Lee / 李唯" __position__ = [ "Software Engineer @ Rakuten Slice", "Volunteer @ PyCon Taiwan" ] __twitter__ = " @clleew" __github__ = " Lee-W" __blog__ = " http://lee-w.github.io"
7. @clleew __date__ = "5-6 Sep" __location__ = "Tainan, Taiwan" __twitter__ = " @PyConTW" __note__ = """ Possibly the first physical PyCon after COVID-19 """ $ cat pycontw_2020.py
8. @clleew Who have ever used git?
9. @clleew Who have ever commit like this? git commit -m "update"
10. @clleew
11. @clleew
12. @clleew Why not use "update" as a commit message? • Hard to find the right commit to rollback • Hard to know the trace of this change during code review • Tend to make a lot of changes in a single commit
 (because you don't know how to describe these changes)
13. @clleew Why should we write good commit message? • Guide teams on how code changes should be made • Save reviewers' time to know the intention of changes • Give newcomer a clear view of the evolvement of projects
14. @clleew How to write good commit messages? 1. Separate subject from body with a blank line 2. Limit the subject line to 50 characters 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. Use the body to explain what and why vs. how
15. @clleew But... It's easy to forget all the guidelines when you enter "git commit"
16. @clleew commitizen-tools
17. @clleew
18. @clleew The command line tool for creating committing rules
19. @clleew cookiecutter template for creating customized rule
20. @clleew The GitHub Actions and hooks for utilizing the messages
21. @clleew The GitHub Actions and hooks for utilizing the messages that we're planning to implement in the future
22. @clleew Commitizen
23. @clleew Install Commitizen $ python -m pip install pipx $ python -m pipx install commitizen $ cz # or git cz
24. @clleew cz init Initialize commitizen configuration
25. @clleew cz init Initialize commitizen configuration
26. @clleew cz init Initialize commitizen configuration
27. @clleew [tool.commitizen] name = "cz_conventional_commits" version = "0.0.1" tag_format = "$version" Commitizen Configuration
28. @clleew cz commit type of this change A hint for users to break down multiple changes into separate commits
29. @clleew cz commit scope of this change
30. @clleew cz commit
 a short description
31. @clleew cz commit
 whether it's a breaking change
32. @clleew cz commit
 detail description of this change
33. @clleew cz commit
 footer reference to the ticket or issue related to this change
34. @clleew Standardized git commits
35. @clleew Standardized git commits git log --format="%s"
36. @clleew What if I forget to use "cz commit" to do git commit?
37. @clleew Enforce commit check through pre-commit 1.Create .pre-commit-config.yaml
 
 
 
 
 2.Install pre-commit hook repos: - repo: https://github.com/commitizen-tools/commitizen rev: v1.22.2 hooks: - id: commitizen stages: [commit-msg] $ python -m pipx install pre-commit $ pre-commit install -t commit-msg
38. @clleew git will block it if your commit does not follow the rule.
39. @clleew git will block it if your commit does not follow the rule.
40. @clleew git will block it if your commit does not follow the rule.
41. @clleew How can we utilize these standardize commit messages? • Auto versioning • Auto generate changelog
42. @clleew Semantic Versioning x.y.z MAJOR Minor Patch
43. @clleew • MAJOR: incompatible API changes • MINOR: add backwards compatible functionality • PATCH: make backwards compatible bug fixes Semantic Versioning
44. @clleew Bump Version • MAJOR: breaking change • MINOR: feat • PATCH: fix, refactor, perf
45. @clleew Bump Version • MAJOR: breaking change • MINOR: feat • PATCH: fix, refactor, perf
46. @clleew Bump Version $ cz bump
47. @clleew The commit with the highest version to bump is feat (The original version of the sample project is 1.2.0.) Bump Version $ cz bump
48. @clleew message tag to create: 1.3.0 increment detected: MINOR The commit with the highest version to bump is feat (The original version of the sample project is 1.2.0.) Bump Version $ cz bump
49. @clleew Bump Version in Source File [tool.commitizen] name = "cz_conventional_commits" version = "0.0.1" tag_format = "$version" version_files = [ "my_project/__init__.py" ]
50. @clleew Keep a changelog
51. @clleew Auto generate changelog $ cz changelog
52. @clleew Auto generate changelog $ cz changelog # CHANGELOG ## Unreleased ### feat - add cov task to check test coverage - make scripts a package - add pylint task - add mypy, flake8 style check - add reformat task to reformat code through black
53. @clleew Auto generate changelog • Generate changelog only from last created version
 (avoid wiping out the manual change in changelog file) • Generate changelog when bumping version $ cz cz changelog --incremental $ cz bump --changelog
54. @clleew Cutsomization 1. Use "cz-customize" in configuration file • No Python Knowledge needed • Suitable for basic rules 2. Creating a customized python package • Suitable for advance usage
 (e.g., customize changelog parser and hook)
55. @clleew Back to our config file [tool.commitizen] name = "cz_conventional_commits" version = "0.0.1" tag_format = "$version"
56. @clleew cz_customize [tool.commitizen] name = "cz_customize"
57. @clleew cz_customize [tool.commitizen] name = "cz_customize" [tool.commitizen.customize] message_template = "{{change_type}}: {{message}}" bump_pattern = "^(break|new|hotfix)" bump_map = {"break" = "MAJOR", "new" = "MINOR", "hotfix" = "PATCH"} [tool.commitizen] name = "cz_customize"
58. @clleew cz_customize [tool.commitizen] name = "cz_customize" [tool.commitizen.customize] message_template = "{{change_type}}: {{message}}" bump_pattern = "^(break|new|hotfix)" bump_map = {"break" = "MAJOR", "new" = "MINOR", "hotfix" = "PATCH"} [[tool.commitizen.customize.questions]] type = "list" name = "change_type" choices = [ {value = "feature", name = "feature: A new feature."}, {value = "hotfix", name = "bug fix: A bug fix."} ] message = "Select the type of change you are committing" [[tool.commitizen.customize.questions]] type = "input" name = "message" message = "Body." [tool.commitizen] name = "cz_customize" [tool.commitizen.customize] message_template = "{{change_type}}: {{message}}" bump_pattern = "^(break|new|hotfix)" bump_map = {"break" = "MAJOR", "new" = "MINOR", "hotfix" = "PATCH"} [tool.commitizen] name = "cz_customize"
59. @clleew Customize through python package from commitizen.cz.base import BaseCommitizen class JiraCz(BaseCommitizen): def questions(self) -> list: """Questions regarding the commit message.""" questions = [ {"type": "input", "name": "title", "message": "Commit title"}, {"type": "input", "name": "issue", "message": "Jira Issue number:"}, ] return questions def message(self, answers: dict) -> str: """Generate the message with the given answers.""" return f"{answers['title']} (#{answers['issue']})" discover_this = JiraCz # used by the plug-in system
60. @clleew commitizen-tools/commitizen_cz_template
61. @clleew Join us and make commitizen-tools better ⭐
62. @clleew Reference • commitizen-tools • Conventional Commits • Semantic Versioning • Keep a changelog • How to Write a Git Commit Message