Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

3e049ed33195d00a8b745b16c63dce6e?s=128

Lee Wei

June 18, 2020
Tweet

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