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

Lee Wei

June 18, 2020
Tweet

More Decks by Lee Wei

Other Decks in Programming

Transcript

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

    View full-size slide

  2. @clleew
    2019/10/24 - Taipei.py

    View full-size slide

  3. @clleew
    2019/10/24 - Taipei.py

    View full-size slide

  4. @clleew
    Slide

    View full-size slide

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

    View full-size slide

  6. @clleew
    __date__ = "5-6 Sep"
    __location__ = "Tainan, Taiwan"
    __twitter__ = " @PyConTW"
    __note__ = """
    Possibly the first physical PyCon
    after COVID-19
    """
    $ cat pycontw_2020.py

    View full-size slide

  7. @clleew
    Who have ever used git?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  10. @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

    View full-size slide

  11. @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

    View full-size slide

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

    View full-size slide

  13. @clleew
    commitizen-tools

    View full-size slide

  14. @clleew
    The command line tool for creating committing rules

    View full-size slide

  15. @clleew
    cookiecutter template for creating customized rule

    View full-size slide

  16. @clleew
    The GitHub Actions and hooks for utilizing the messages

    View full-size slide

  17. @clleew
    The GitHub Actions and hooks for utilizing the messages
    that we're planning to implement in the future

    View full-size slide

  18. @clleew
    Commitizen

    View full-size slide

  19. @clleew
    Install Commitizen
    $ python -m pip install pipx
    $ python -m pipx install commitizen
    $ cz # or git cz

    View full-size slide

  20. @clleew
    cz init
    Initialize commitizen configuration

    View full-size slide

  21. @clleew
    cz init
    Initialize commitizen configuration

    View full-size slide

  22. @clleew
    cz init
    Initialize commitizen configuration

    View full-size slide

  23. @clleew
    [tool.commitizen]
    name = "cz_conventional_commits"
    version = "0.0.1"
    tag_format = "$version"
    Commitizen Configuration

    View full-size slide

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

    View full-size slide

  25. @clleew
    cz commit
    scope of this change

    View full-size slide

  26. @clleew
    cz commit

    a short description

    View full-size slide

  27. @clleew
    cz commit

    whether it's a breaking change

    View full-size slide

  28. @clleew
    cz commit

    detail description of this change

    View full-size slide

  29. @clleew
    cz commit

    footer
    reference to the ticket or issue related to this change

    View full-size slide

  30. @clleew
    Standardized git commits

    View full-size slide

  31. @clleew
    Standardized git commits
    git log --format="%s"

    View full-size slide

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

    View full-size slide

  33. @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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  37. @clleew
    How can we utilize these
    standardize commit messages?
    • Auto versioning

    • Auto generate changelog

    View full-size slide

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

    View full-size slide

  39. @clleew
    • MAJOR: incompatible API changes

    • MINOR: add backwards compatible functionality

    • PATCH: make backwards compatible bug fixes
    Semantic Versioning

    View full-size slide

  40. @clleew
    Bump Version
    • MAJOR: breaking change

    • MINOR: feat

    • PATCH: fix, refactor, perf

    View full-size slide

  41. @clleew
    Bump Version
    • MAJOR: breaking change

    • MINOR: feat

    • PATCH: fix, refactor, perf

    View full-size slide

  42. @clleew
    Bump Version
    $ cz bump

    View full-size slide

  43. @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

    View full-size slide

  44. @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

    View full-size slide

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

    View full-size slide

  46. @clleew
    Keep a changelog

    View full-size slide

  47. @clleew
    Auto generate changelog
    $ cz changelog

    View full-size slide

  48. @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

    View full-size slide

  49. @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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  55. @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

    View full-size slide

  56. @clleew
    commitizen-tools/commitizen_cz_template

    View full-size slide

  57. @clleew
    Join us and
    make commitizen-tools better ⭐

    View full-size slide

  58. @clleew
    Reference
    • commitizen-tools

    • Conventional Commits

    • Semantic Versioning

    • Keep a changelog

    • How to Write a Git Commit Message

    View full-size slide