Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

commitizen-tools: What can we gain from craftin...

Lee Wei
June 18, 2020

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

Lee Wei

June 18, 2020
Tweet

More Decks by Lee Wei

Other Decks in Programming

Transcript

  1. @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"
  2. @clleew __date__ = "5-6 Sep" __location__ = "Tainan, Taiwan" __twitter__

    = " @PyConTW" __note__ = """ Possibly the first physical PyCon after COVID-19 """ $ cat pycontw_2020.py
  3. @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)
  4. @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
  5. @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
  6. @clleew The GitHub Actions and hooks for utilizing the messages

    that we're planning to implement in the future
  7. @clleew Install Commitizen $ python -m pip install pipx $

    python -m pipx install commitizen $ cz # or git cz
  8. @clleew cz commit type of this change A hint for

    users to break down multiple changes into separate commits
  9. @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
  10. @clleew How can we utilize these standardize commit messages? •

    Auto versioning • Auto generate changelog
  11. @clleew • MAJOR: incompatible API changes • MINOR: add backwards

    compatible functionality • PATCH: make backwards compatible bug fixes Semantic Versioning
  12. @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
  13. @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
  14. @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" ]
  15. @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
  16. @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
  17. @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)
  18. @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"
  19. @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"
  20. @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
  21. @clleew Reference • commitizen-tools • Conventional Commits • Semantic Versioning

    • Keep a changelog • How to Write a Git Commit Message