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

コミットメッセージ規約 「Conventional Commits」を導入してみよう! / Let's use Conventional Commits

02
April 11, 2022

コミットメッセージ規約 「Conventional Commits」を導入してみよう! / Let's use Conventional Commits

PHPerkaigi 2022 のレギュラートークで使用したスライドです。
https://fortee.jp/phperkaigi-2022/proposal/8acc191a-7625-4dad-afc3-3f52025e6e6b
https://www.youtube.com/watch?v=-npgdvGAnlU

02

April 11, 2022
Tweet

More Decks by 02

Other Decks in Programming

Transcript

  1. 2022/4/11 PHPerKaigi 2022
    @02
    コミットメッセージ規約
    「Conventional Commits」を導入してみよう!
    #phperkaigi #a

    View Slide

  2. #phperkaigi #a
    PHP系カンファレンス登壇 執筆
    BankEnd Software Enginner
    02 大津 和槻
    :@cocoeyes02
    2021/02~ BASE, Inc.
    自己紹介
    登壇応援中!

    View Slide

  3. #phperkaigi #a
    こんなコミットメッセージ見たことありませんか
    3

    View Slide

  4. #phperkaigi #a
    バグを修正した
    wip
    PRで指摘されたので修正
    4
    こんなコミットメッセージ見たことありませんか

    View Slide

  5. #phperkaigi #a
    バグを修正した
    wip
    PRで指摘されたので修正
    コミットは他人が見るものだから、
    他人が書き手の意図を理解できないと❌
    5
    こんなコミットメッセージ見たことありませんか

    View Slide

  6. #phperkaigi #a
    6
    https://speakerdeck.com/cocoeyes02/recommendation-of-readable-commit https://www.praha-inc.com/lab/posts/commit-message
    詳細は過去の登壇資料やアウトプットへ譲ります!
    どんなコミットメッセージがいい?(例題)

    View Slide

  7. #phperkaigi #a
    バグを修正した
    7
    どんなコミットメッセージがいい?(例題)

    View Slide

  8. #phperkaigi #a
    具体的にこのコミットメッセージのどこがまずいか
    ● なんのバグだったのか分からない
    ● どんなの理由で直したのかわからない
    ● コードを見ても直した内容がよく分からない時どうにもできない
    バグを修正した
    8
    どんなコミットメッセージがいい?(例題)

    View Slide

  9. #phperkaigi #a
    バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正
    18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規
    登録ができなかったので、チェックボックスのバリデーションを修正した。
    See-also: https://laravel.com/docs/9.x/validation#rule-required-if
    9
    どんなコミットメッセージがいい?(例題)

    View Slide

  10. #phperkaigi #a
    ● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる
    バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正
    18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規
    登録ができなかったので、チェックボックスのバリデーションを修正した。
    See-also: https://laravel.com/docs/9.x/validation#rule-required-if
    10
    どんなコミットメッセージがいい?(例題)

    View Slide

  11. #phperkaigi #a
    ● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる
    ● 詳細の修正内容がさらに詳しく書いてある
    バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正
    18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規
    登録ができなかったので、チェックボックスのバリデーションを修正した。
    See-also: https://laravel.com/docs/9.x/validation#rule-required-if
    11
    どんなコミットメッセージがいい?(例題)

    View Slide

  12. #phperkaigi #a
    ● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる
    ● 詳細の修正内容がさらに詳しく書いてある
    ● 参考にしたドキュメントのリンクが貼ってある
    バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正
    18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規
    登録ができなかったので、チェックボックスのバリデーションを修正した。
    See-also: https://laravel.com/docs/9.x/validation#rule-required-if
    12
    どんなコミットメッセージがいい?(例題)

    View Slide

  13. #phperkaigi #a
    ● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる
    ● 詳細の修正内容がさらに詳しく書いてある
    ● 参考にしたドキュメントのリンクが貼ってある
    バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正
    18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規
    登録ができなかったので、チェックボックスのバリデーションを修正した。
    See-also: https://laravel.com/docs/9.x/validation#rule-required-if
    13
    どんなコミットメッセージがいい?(例題)

    View Slide

  14. #phperkaigi #a
    力が欲しいか・・・?
    分かりやすいコミットメッセージを
    書けるようになりたい!
    14

    View Slide

  15. #phperkaigi #a
    力が欲しいか・・・?
    分かりやすいコミットメッセージを
    誰でも書けるようになりたい!
    15

    View Slide

  16. #phperkaigi #a
    力が欲しいか・・・?
    そう、Conventional Commits
    ならできます!
    16

    View Slide

  17. Conventional Commits
    とは何か?

    View Slide

  18. #phperkaigi #a
    Conventional Commits とは?
    18
    コミットメッセージの軽量規約
    コミットメッセージの形、プレフィックス、複数のルールと強制度が定められている
    もともとAngularの規約に触発されて生まれた経緯がある他、
    electronやyargsなどで利用されている

    View Slide

  19. #phperkaigi #a
    どんなルールがある規約なの?
    主に以下のようなルールが存在します。
    ● Prefix(接頭辞)に関するルール
    ● タイトルに関するルール
    ● 本文に関するルール
    ● フッターに関するルール
    ● 破壊的変更に関するルール
    例として、なるべく多くのルールを適用したコミットメッセージを使いつつ説明します。
    19

    View Slide

  20. #phperkaigi #a
    どんなルールがある規約なの?
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    20

    View Slide

  21. #phperkaigi #a
    どんなルールがある規約なの?
    Prefix(接頭辞)に関するルール (一部)
    ● コミットは feat や fix などの型から始まり (MUST)、その後ろにはスコープ (OPTIONAL) と !
    (OPTIONAL) が続き、その後ろにコロンとスペース (REQUIRED) が続く。
    ● スコープを型の後ろに記述してもよい (MAY)。スコープは、コードベースのセクションを記述す
    る括弧で囲まれた名詞にしなければならない (MUST)。例: fix(parser):。
    ● feat と fix 以外の型を使うことができる (MAY)。例: docs: updated ref docs.。
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    21

    View Slide

  22. #phperkaigi #a
    どんなルールがある規約なの?
    タイトルに関するルール
    ● 型/スコープの後ろのコロンとスペースの直後にタイトルが続かなければならない (MUST)。 タ
    イトルはコード変更の短い要約である。例: fix: array parsing issue when multiple spaces
    were contained in string。
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    22

    View Slide

  23. #phperkaigi #a
    どんなルールがある規約なの?
    本文に関するルール
    ● 短いタイトルの後ろにより長いコミットの本文を追加してもよい (MAY)。これはコード変更に関
    する追加の情報を提供する。 本文はタイトルの下の 1 行の空行から始めなければならない
    (MUST)。
    ● コミットの本文は自由な形式であり、改行で区切られた複数の段落で構成することができる
    (MAY)。
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    23

    View Slide

  24. #phperkaigi #a
    どんなルールがある規約なの?
    フッターに関するルール
    ● ひとつ以上のフッターを、本文の下の 1 行の空行に続けて書くことができる (MAY)。 それぞれ
    のフッターは、ひとつの単語トークン、それに続く : か # によるセパレー
    タ、そして文字列の値から構成されなければならない (MUST)。
    ● フッターのトークンは空白の代わりに - を使わなければならない (MUST)。例えば Acked-by と
    する (これは複数段落からなる本文からフッターを区別するのに役立つ)。
    ● フッターの値にはスペースと改行を含めることができる (MAY)。
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    24

    View Slide

  25. #phperkaigi #a
    どんなルールがある規約なの?
    破壊的変更に関するルール (一部)
    ● 破壊的変更は、コミットの型/スコープの接頭辞か、フッターによって明示されなければならな
    い (MUST)。
    ● 破壊的変更が型/スコープの接頭辞として含まれる場合は、: の直前に ! を用いて明示されねばな
    らない (MUST)。! が使用すれた場合には、 フッターから BREAKING CHANGE: を省略しても
    よい (MAY)。その場合はコミットのタイトル部分で破壊的変更の内容を説明することになる
    (SHALL)。
    feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲
    管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。
    BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われる
    See-also: https://readouble.com/laravel/9.x/ja/authentication.html
    Issue #101
    25

    View Slide

  26. #phperkaigi #a
    誰でもできるのか・・・?
    これだけのルールを覚えるのは面倒
    26

    View Slide

  27. #phperkaigi #a
    誰でもできるのか・・・?
    自分だけルールを覚えたとしても
    他の人が覚えている保証は・・・
    27

    View Slide

  28. #phperkaigi #a
    誰でもできるのか・・・?
    そんな人のためのツールがあります
    28

    View Slide

  29. Conventional Commitsに沿った
    コミットメッセージ作成

    View Slide

  30. #phperkaigi #a
    今回使うツール
    30
    ramsey/conventional-commits
    Conventional Commits の仕様に従ってコミットメッセージを作成したり、
    バリデーションができる PHP ライブラリ。
    CaptainHookと呼ばれる、PHP製のGit フックマネージャーを使用している。

    View Slide

  31. #phperkaigi #a
    ramsey/conventional-commitsでできること
    31
    ● 対話式によるコミットメッセージ作成
    ○ Prefix(接頭辞)、タイトル、本文、フッター、破壊的変更の有無
    ○ git commitコマンド時の強制実行の有無
    ● Conventional Commitsに沿っていないコミットメッセージのバリデーション
    ○ バリデーション失敗時にコミット阻止実行の有無

    View Slide

  32. #phperkaigi #a
    対話式でコミットメッセージを作成している様子
    32

    View Slide

  33. #phperkaigi #a
    こんな感じのコミットメッセージも作成できます
    33

    View Slide

  34. #phperkaigi #a
    こんな感じのコミットメッセージも作成できます
    34
    さらにこのコミットメッセージを使って、CHANGELOGの自動生成ができます!

    View Slide

  35. PHPプロジェクトで
    CHANGELOGを自動生成

    View Slide

  36. #phperkaigi #a
    今回使うツール
    36
    marcocesarato/php-conventional-changelog
    CHANGELOG を生成し、Conventional Commits の仕様に準じた
    セマンティックバージョニングでバージョン管理をするツールです。

    View Slide

  37. #phperkaigi #a
    php-conventional-changelogでできること
    37
    ● CHANGELOGの自動作成
    ○ Conventional Commitsに沿ったコミットメッセージから自動作成する
    ■ Prefix(接頭辞)、タイトル、破壊的変更の有無などから
    ● 上げるべきバージョンを計算する
    ○ featのPrefixであれば、マイナーバージョンを上げる (1.0.0 -> 1.1.0)
    ○ fixのPrefixであれば、パッチバージョンを上げる (1.0.0 -> 1.0.1)
    ○ 破壊的変更があれば、メジャーバージョンを上げる (1.0.0 -> 2.0.0)

    View Slide

  38. #phperkaigi #a
    作成している様子
    38

    View Slide

  39. #phperkaigi #a
    作成したCHANGELOG
    39

    View Slide

  40. #phperkaigi #a
    最後に
    40
    今回はPHPerKaigiですので、ツール系もPHP製のツールを紹介しました。
    ですが、公式ページにはPHP以外のツールもいっぱい紹介されております。
    Golangだったり、Rubyだったり、JSだったり・・・。
    誰もが分かりやすいコミットメッセージを書ける世界を目指して、
    今回の発表が少しでも役に立てれば幸いです!

    View Slide

  41. #phperkaigi #a
    https://github.com/cocoeyes02/phperkaigi2022_conventional_commits
    今回のリポジトリ

    View Slide

  42. #phperkaigi #a
    ● Conventional Commits
    https://www.conventionalcommits.org/ja/v1.0.0/
    ● ramsey/conventional-commits
    https://github.com/ramsey/conventional-commits
    ● marcocesarato/php-conventional-changelog
    https://github.com/marcocesarato/php-conventional-changelog
    参考文献

    View Slide