PHPerkaigi 2022 のレギュラートークで使用したスライドです。 https://fortee.jp/phperkaigi-2022/proposal/8acc191a-7625-4dad-afc3-3f52025e6e6b https://www.youtube.com/watch?v=-npgdvGAnlU
2022/4/11 PHPerKaigi 2022@02コミットメッセージ規約「Conventional Commits」を導入してみよう！#phperkaigi #a
View Slide
#phperkaigi #aPHP系カンファレンス登壇 執筆BankEnd Software Enginner02 大津 和槻：@cocoeyes022021/02~ BASE, Inc.自己紹介登壇応援中！
#phperkaigi #aこんなコミットメッセージ見たことありませんか3
#phperkaigi #aバグを修正したwipPRで指摘されたので修正4こんなコミットメッセージ見たことありませんか
#phperkaigi #aバグを修正したwipPRで指摘されたので修正コミットは他人が見るものだから、他人が書き手の意図を理解できないと❌5こんなコミットメッセージ見たことありませんか
#phperkaigi #a6https://speakerdeck.com/cocoeyes02/recommendation-of-readable-commit https://www.praha-inc.com/lab/posts/commit-message詳細は過去の登壇資料やアウトプットへ譲ります！どんなコミットメッセージがいい？（例題）
#phperkaigi #aバグを修正した7どんなコミットメッセージがいい？（例題）
#phperkaigi #a具体的にこのコミットメッセージのどこがまずいか● なんのバグだったのか分からない● どんなの理由で直したのかわからない● コードを見ても直した内容がよく分からない時どうにもできないバグを修正した8どんなコミットメッセージがいい？（例題）
#phperkaigi #aバグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規登録ができなかったので、チェックボックスのバリデーションを修正した。See-also: https://laravel.com/docs/9.x/validation#rule-required-if9どんなコミットメッセージがいい？（例題）
#phperkaigi #a● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかるバグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規登録ができなかったので、チェックボックスのバリデーションを修正した。See-also: https://laravel.com/docs/9.x/validation#rule-required-if10どんなコミットメッセージがいい？（例題）
#phperkaigi #a● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる● 詳細の修正内容がさらに詳しく書いてあるバグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規登録ができなかったので、チェックボックスのバリデーションを修正した。See-also: https://laravel.com/docs/9.x/validation#rule-required-if11どんなコミットメッセージがいい？（例題）
#phperkaigi #a● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる● 詳細の修正内容がさらに詳しく書いてある● 参考にしたドキュメントのリンクが貼ってあるバグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規登録ができなかったので、チェックボックスのバリデーションを修正した。See-also: https://laravel.com/docs/9.x/validation#rule-required-if12どんなコミットメッセージがいい？（例題）
#phperkaigi #a● customerにまつわる機能で、18歳未満が新規登録できない不具合であるとわかる● 詳細の修正内容がさらに詳しく書いてある● 参考にしたドキュメントのリンクが貼ってあるバグを修正した fix(customer): 18歳未満が新規登録できなかったので、バリデーションを修正18歳未満に求められる保護者の同意のチェックボックスにチェックをつけても新規登録ができなかったので、チェックボックスのバリデーションを修正した。See-also: https://laravel.com/docs/9.x/validation#rule-required-if13どんなコミットメッセージがいい？（例題）
#phperkaigi #a力が欲しいか・・・？分かりやすいコミットメッセージを書けるようになりたい！14
#phperkaigi #a力が欲しいか・・・？分かりやすいコミットメッセージを誰でも書けるようになりたい！15
#phperkaigi #a力が欲しいか・・・？そう、Conventional Commitsならできます！16
Conventional Commitsとは何か？
#phperkaigi #aConventional Commits とは？18コミットメッセージの軽量規約コミットメッセージの形、プレフィックス、複数のルールと強制度が定められているもともとAngularの規約に触発されて生まれた経緯がある他、electronやyargsなどで利用されている
#phperkaigi #aどんなルールがある規約なの？主に以下のようなルールが存在します。● Prefix（接頭辞）に関するルール● タイトルに関するルール● 本文に関するルール● フッターに関するルール● 破壊的変更に関するルール例として、なるべく多くのルールを適用したコミットメッセージを使いつつ説明します。19
#phperkaigi #aどんなルールがある規約なの？feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われるSee-also: https://readouble.com/laravel/9.x/ja/authentication.htmlIssue #10120
#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.htmlIssue #10121
#phperkaigi #aどんなルールがある規約なの？タイトルに関するルール● 型/スコープの後ろのコロンとスペースの直後にタイトルが続かなければならない (MUST)。 タイトルはコード変更の短い要約である。例: fix: array parsing issue when multiple spaceswere contained in string。feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われるSee-also: https://readouble.com/laravel/9.x/ja/authentication.htmlIssue #10122
#phperkaigi #aどんなルールがある規約なの？本文に関するルール● 短いタイトルの後ろにより長いコミットの本文を追加してもよい (MAY)。これはコード変更に関する追加の情報を提供する。 本文はタイトルの下の 1 行の空行から始めなければならない(MUST)。● コミットの本文は自由な形式であり、改行で区切られた複数の段落で構成することができる(MAY)。feat(administer)!: 管理者の認証や認可を新しいモデルへ委譲管理者を別のモデルとして扱いたいので、管理者の認証や認可をUserモデルから新規Administerモデルへ委譲した。BREAKING CHANGE: 会員と管理者で同じUserモデルを使っていたが、Userモデルから管理者として機能が失われるSee-also: https://readouble.com/laravel/9.x/ja/authentication.htmlIssue #10123
#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.htmlIssue #10124
#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.htmlIssue #10125
#phperkaigi #a誰でもできるのか・・・？これだけのルールを覚えるのは面倒26
#phperkaigi #a誰でもできるのか・・・？自分だけルールを覚えたとしても他の人が覚えている保証は・・・27
#phperkaigi #a誰でもできるのか・・・？そんな人のためのツールがあります28
Conventional Commitsに沿ったコミットメッセージ作成
#phperkaigi #a今回使うツール30ramsey/conventional-commitsConventional Commits の仕様に従ってコミットメッセージを作成したり、バリデーションができる PHP ライブラリ。CaptainHookと呼ばれる、PHP製のGit フックマネージャーを使用している。
#phperkaigi #aramsey/conventional-commitsでできること31● 対話式によるコミットメッセージ作成○ Prefix（接頭辞）、タイトル、本文、フッター、破壊的変更の有無○ git commitコマンド時の強制実行の有無● Conventional Commitsに沿っていないコミットメッセージのバリデーション○ バリデーション失敗時にコミット阻止実行の有無
#phperkaigi #a対話式でコミットメッセージを作成している様子32
#phperkaigi #aこんな感じのコミットメッセージも作成できます33
#phperkaigi #aこんな感じのコミットメッセージも作成できます34さらにこのコミットメッセージを使って、CHANGELOGの自動生成ができます！
PHPプロジェクトでCHANGELOGを自動生成
#phperkaigi #a今回使うツール36marcocesarato/php-conventional-changelogCHANGELOG を生成し、Conventional Commits の仕様に準じたセマンティックバージョニングでバージョン管理をするツールです。
#phperkaigi #aphp-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)
#phperkaigi #a作成している様子38
#phperkaigi #a作成したCHANGELOG39
#phperkaigi #a最後に40今回はPHPerKaigiですので、ツール系もPHP製のツールを紹介しました。ですが、公式ページにはPHP以外のツールもいっぱい紹介されております。Golangだったり、Rubyだったり、JSだったり・・・。誰もが分かりやすいコミットメッセージを書ける世界を目指して、今回の発表が少しでも役に立てれば幸いです！
#phperkaigi #ahttps://github.com/cocoeyes02/phperkaigi2022_conventional_commits今回のリポジトリ
#phperkaigi #a● Conventional Commitshttps://www.conventionalcommits.org/ja/v1.0.0/● ramsey/conventional-commitshttps://github.com/ramsey/conventional-commits● marcocesarato/php-conventional-changeloghttps://github.com/marcocesarato/php-conventional-changelog参考文献
cocoeyes02
zakky21
ivargrimstad
varu3
alli83
riku929hr
hollycummins
deepu105
tnishinaga
seike460
dunglas
fornewid
antyadev
holman
kevinliebholz
kastner
colly
michaelherold
chriscoyier
jnunemaker
chrisshort
quramy
myddelton
afnizarnur