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

@clleew 2019/10/24 - Taipei.py

@clleew 2019/10/24 - Taipei.py

@clleew

@clleew Slide

@clleew __name__ = 李唯 / Wei Lee __position__ = [ Software Engineer @ Rakuten Slice, Volunteer @ PyCon Taiwan, "Maintainer of commitizen-tools, ] __twitter__ = @clleew __github__ = Lee-W __blog__ = http://lee-w.github.io $ cat speaker.py

@clleew File "speaker.py", line 1 __name__ = 李唯 / Wei Lee ^ SyntaxError: invalid syntax $ python speaker.py

@clleew Who have ever used git?

@clleew Who have ever commit like this? git commit -m "update"

@clleew

@clleew

@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)

@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

@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

@clleew But... It's easy to forget all the guidelines when you enter "git commit"

@clleew commitizen-tools

@clleew

@clleew The command line tool for creating committing rules

@clleew GitHub Action that runs commitizen

@clleew cookiecutter template for creating customized rule

@clleew Commitizen

@clleew Install Commitizen

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration

@clleew Initialize commitizen configuration We'll discuss more about it later.

@clleew [tool.commitizen] name = "cz_conventional_commits" version = "0.0.1" tag_format = "$version" Commtizen configuration pyproject.toml

@clleew cz commit type of this change A hint for users to break down multiple changes into separate commits

@clleew $ cz commit scope of this change

@clleew $ cz commit
 a short description

@clleew $ cz commit
 detail description of this change

@clleew $ cz commit
 whether it's a breaking change

@clleew $ cz commit
 footer reference to the ticket or issue related to this change

@clleew How does the commit look like? feat(tainan.py): awesome meetup hope everyone enjoys this talk https://www.meetup.com/Tainan-py-Python-Tainan-User-Group/events/ 272270687/

@clleew $ cz commit

@clleew $ cz commit

@clleew $ cz commit

@clleew Standardized git commits

@clleew What if I forget to use "cz commit" to do git commit?

@clleew Enforce commit check through pre-commit 1.Create .pre-commit-config.yaml
 
 
 
 
 2.Install pre-commit hook repos: - hooks: - id: commitizen stages: - commit-msg repo: https://github.com/commitizen-tools/commitizen rev: v2.1.0

@clleew It looks familiar

@clleew It looks familiar We already initialize it when running "cz init".

@clleew git will block it if your commit does not follow the rule.

@clleew git will block it if your commit does not follow the rule.

@clleew git will block it if your commit does not follow the rule.

@clleew How can we utilize these standardize commit messages? • Auto versioning • Auto generate changelog

@clleew Semantic Versioning x.y.z MAJOR Minor Patch

@clleew • MAJOR: incompatible API changes • MINOR: add backwards compatible functionality • PATCH: make backwards compatible bug fixes Semantic Versioning

@clleew Bump Version • MAJOR: breaking change • MINOR: feat • PATCH: fix, refactor, perf

@clleew Bump Version • MAJOR: breaking change • MINOR: feat • PATCH: fix, refactor, perf

@clleew Bump Version $ cz bump

@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

@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

@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" ]

@clleew Keep a changelog

@clleew Auto generate changelog

@clleew Auto generate 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

@clleew Auto generate changelog

@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)

@clleew Back to our config file [tool.commitizen] name = "cz_conventional_commits" version = "0.0.1" tag_format = "$version"

@clleew cz_customize [tool.commitizen] name = "cz_customize"

@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"

@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"

@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

@clleew commitizen-tools/commitizen_cz_template

@clleew Join us and make commitizen-tools better ⭐

@clleew Reference • commitizen-tools • Conventional Commits • Semantic Versioning • Keep a changelog • How to Write a Git Commit Message