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

PHPerkaigi 2022 のレギュラートークで使用したスライドです。
https://fortee.jp/phperkaigi-2022/proposal/01dda7a8-3f5d-4141-84f8-f20dd7249e02

Transcript

1. 2022/4/11 PHPerKaigi 2022 @02 コミットメッセージ規約 「Conventional Commits」を導入してみよう！ #phperkaigi #a
2. #phperkaigi #a PHP系カンファレンス登壇 執筆 BankEnd Software Enginner 02 大津 和槻 ：@cocoeyes02 2021/02~ BASE, Inc. 自己紹介 登壇応援中！
3. #phperkaigi #a こんなコミットメッセージ見たことありませんか 3
4. #phperkaigi #a バグを修正した wip PRで指摘されたので修正 4 こんなコミットメッセージ見たことありませんか
5. #phperkaigi #a バグを修正した wip PRで指摘されたので修正 コミットは他人が見るものだから、 他人が書き手の意図を理解できないと❌ 5 こんなコミットメッセージ見たことありませんか
6. #phperkaigi #a 6 https://speakerdeck.com/cocoeyes02/recommendation-of-readable-commit https://www.praha-inc.com/lab/posts/commit-message 詳細は過去の登壇資料やアウトプットへ譲ります！ どんなコミットメッセージがいい？（例題）
7. #phperkaigi #a バグを修正した 7 どんなコミットメッセージがいい？（例題）
8. #phperkaigi #a 具体的にこのコミットメッセージのどこがまずいか • なんのバグだったのか分からない • どんなの理由で直したのかわからない • コードを見ても直した内容がよく分からない時どうにもできない バグを修正した 8 どんなコミットメッセージがいい？（例題）
9. #phperkaigi #a バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正 18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規 登録ができなかったので、チェックボックスのバリデーションを修正した。 See-also: https://laravel.com/docs/9.x/validation#rule-required-if 9 どんなコミットメッセージがいい？（例題）
10. #phperkaigi #a • customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正 18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規 登録ができなかったので、チェックボックスのバリデーションを修正した。 See-also: https://laravel.com/docs/9.x/validation#rule-required-if 10 どんなコミットメッセージがいい？（例題）
11. #phperkaigi #a • customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる • 詳細の修正内容がさらに詳しく書いてある バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正 18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規 登録ができなかったので、チェックボックスのバリデーションを修正した。 See-also: https://laravel.com/docs/9.x/validation#rule-required-if 11 どんなコミットメッセージがいい？（例題）
12. #phperkaigi #a • customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる • 詳細の修正内容がさらに詳しく書いてある • 参考にしたドキュメントのリンクが貼ってある バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正 18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規 登録ができなかったので、チェックボックスのバリデーションを修正した。 See-also: https://laravel.com/docs/9.x/validation#rule-required-if 12 どんなコミットメッセージがいい？（例題）
13. #phperkaigi #a • customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる • 詳細の修正内容がさらに詳しく書いてある • 参考にしたドキュメントのリンクが貼ってある バグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正 18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規 登録ができなかったので、チェックボックスのバリデーションを修正した。 See-also: https://laravel.com/docs/9.x/validation#rule-required-if 13 どんなコミットメッセージがいい？（例題）
14. #phperkaigi #a 力が欲しいか・・・？ 分かりやすいコミットメッセージを 書けるようになりたい！ 14
15. #phperkaigi #a 力が欲しいか・・・？ 分かりやすいコミットメッセージを 誰でも書けるようになりたい！ 15
16. #phperkaigi #a 力が欲しいか・・・？ そう、Conventional Commits ならできます！ 16
17. Conventional Commits とは何か？
18. #phperkaigi #a Conventional Commits とは？ 18 コミットメッセージの軽量規約 コミットメッセージの形、プレフィックス、複数のルールと強制度が定められている もともとAngularの規約に触発されて生まれた経緯がある他、 electronやyargsなどで利用されている
19. #phperkaigi #a どんなルールがある規約なの？ 主に以下のようなルールが存在します。 • Prefix（接頭辞）に関するルール • タイトルに関するルール • 本文に関するルール • フッターに関するルール • 破壊的変更に関するルール 例として、なるべく多くのルールを適用したコミットメッセージを使いつつ説明します。 19
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
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
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
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
24. #phperkaigi #a どんなルールがある規約なの？ フッターに関するルール • ひとつ以上のフッターを、本文の下の 1 行の空行に続けて書くことができる (MAY)。 それぞれ のフッターは、ひとつの単語トークン、それに続く :<space> か <space># によるセパレー タ、そして文字列の値から構成されなければならない (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
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
26. #phperkaigi #a 誰でもできるのか・・・？ これだけのルールを覚えるのは面倒 26
27. #phperkaigi #a 誰でもできるのか・・・？ 自分だけルールを覚えたとしても 他の人が覚えている保証は・・・ 27
28. #phperkaigi #a 誰でもできるのか・・・？ そんな人のためのツールがあります 28
29. Conventional Commitsに沿った コミットメッセージ作成
30. #phperkaigi #a 今回使うツール 30 ramsey/conventional-commits Conventional Commits の仕様に従ってコミットメッセージを作成したり、 バリデーションができる PHP ライブラリ。 CaptainHookと呼ばれる、PHP製のGit フックマネージャーを使用している。
31. #phperkaigi #a ramsey/conventional-commitsでできること 31 • 対話式によるコミットメッセージ作成 ◦ Prefix（接頭辞）、タイトル、本文、フッター、破壊的変更の有無 ◦ git commitコマンド時の強制実行の有無 • Conventional Commitsに沿っていないコミットメッセージのバリデーション ◦ バリデーション失敗時にコミット阻止実行の有無
32. #phperkaigi #a 対話式でコミットメッセージを作成している様子 32
33. #phperkaigi #a こんな感じのコミットメッセージも作成できます 33
34. #phperkaigi #a こんな感じのコミットメッセージも作成できます 34 さらにこのコミットメッセージを使って、CHANGELOGの自動生成ができます！
35. PHPプロジェクトで CHANGELOGを自動生成
36. #phperkaigi #a 今回使うツール 36 marcocesarato/php-conventional-changelog CHANGELOG を生成し、Conventional Commits の仕様に準じた セマンティックバージョニングでバージョン管理をするツールです。
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)
38. #phperkaigi #a 作成している様子 38
39. #phperkaigi #a 作成したCHANGELOG 39
40. #phperkaigi #a 最後に 40 今回はPHPerKaigiですので、ツール系もPHP製のツールを紹介しました。 ですが、公式ページにはPHP以外のツールもいっぱい紹介されております。 Golangだったり、Rubyだったり、JSだったり・・・。 誰もが分かりやすいコミットメッセージを書ける世界を目指して、 今回の発表が少しでも役に立てれば幸いです！
41. #phperkaigi #a https://github.com/cocoeyes02/phperkaigi2022_conventional_commits 今回のリポジトリ
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 参考文献