本記事について
この記事は CoreBluetoothForUnity Advent Calendar 2023 の21日目の記事です。
コミットメッセージ、プルリクエスト(以後プルリクと書きます)、リリースノートあたりの使い方を書きます。
環境
- CoreBluetoothForUnity 0.4.6
開発方針
以下を満たせるように開発したいなと考えていました。
-
利用者に関して
- 利用者がプルリクやコミットメッセージを見て不安にならないようにある程度綺麗に書く
- バージョンごとの違いを確認するためにリリースノートは必須
- 海外の方にも安心して使ってほしい
-
開発者に関して
- あまり複雑すぎるフローにして作業コスト上がるのは避けたい
- 後からみて内容を把握できるようにプルリクやコミットメッセージにコミット内容にない情報を付加する
それを踏まえて以下のような方針で開発しています。
- ブランチ運用
- 基本 Gitflow に準拠
- コミットメッセージ
- 最初の一行は英語で書く。二行目以降は日本語でも良い
- コミットメッセージに prefix つけるルールは使わない
- プルリク
- タイトルは英語にする。タイトル以外は日本語でも良い
- 見出しの一部は英語にする
- Description
- Background
- Test 等
- 紐づく issue がある場合は URL を記載する (リリース告知前は基本ない)
- リリースノート自動生成のためのラベルを手動で付与する
- リリース
- リリースノートは自動生成
- GitHub の「リリース」を作成したタイミングで npmjs へデプロイする GitHub Actions が走る
これらの詳細について書いていきます。
プルリクの例
add NativeCallbacks Class to avoid depending on UnityEngine #68
インタフェース切って依存切るという内容のプルリクです。
例えば、PR 概要が
DocFX でドキュメント生成するためにインタフェースを切って依存を切る
の一行だった場合、なぜインタフェースを切る必要があるのかの情報がありません。
また、そのあたりの理由をコードに直接コメントで書くということもあまりないでしょう。
この情報をプルリクに書くことで未来の自分または誰かが幸せになれるかもしれません。
(実際私は記事を書くときに各プルリクを見直したりします。)
また、「なぜ依存性を切る必要か」の次は「なぜ依存性を切る方法としてXXを選択したのか」のように開発する上でのいろんな判断とその理由について残しておくと良いと思っています。
コミットメッセージにもプルリクと同じようなことを書きます。
コミットメッセージに情報をがっつり書いて修正の必要もないときにはプルリクに「詳細はコミットメッセージみてください」と記述して済ませる場合もあります。
プルリクのほうがコメント修正が容易なため、プルリクに情報を整理することのほうが多いです。
そして、それぞれコミットメッセージのの一行目は英語です。
こうしておくとプルリクのコミットタブや、GitLens の FileHistory 等で英語がずらっと表示されます。
もしここが日本語だったら、英語圏の人にとってはつらいだろうなということで英語にしています。
詳細は英語で書くの大変なのでブラウザで翻訳してくださいの気持ちです。
コミットメッセージを何で書いているか
VSCode の Git 拡張機能か、SourceTree で書いています。
なんでもいいと思います！
プルリクの作成の仕方
これはコマンドでやったほうが圧倒的に速いです。
GitHub CLI を使用しています。
リリース方法について
流れの順番で書いていきます。
まず develop ブランチまたは適当なブランチで package.json の version を上げます(手動)
そして、それをマージします。
main ブランチへのプルリクはリリースノートに反映する必要がないため ignore-for-release のラベルを付与します。
main にリリースしたい変更が反映されたらリリースページに移動
右上の Draft a new release をクリックして新しくリリースを作成します。
このときに以下を行います。
- 新しいタグを切る (package.json に記載したバージョン)
- リリースノートを自動生成ボタンを押す。
- ラベルの付け忘れとかがあればこのタイミングで修正
- 問題なければリリースを作成
リリースノート自動生成における分類は release.yml に記載されています。
実際にどんなリリースノートが生成されるかは以下のリンクから確認できます。
リリースの作成が成功したら GitHub Actions で npmjs へのデプロイが走ります。
この Action に関しては中身見ればやっていることはわかると思うため説明は省略します。
リリースノートで使用するタグについて
タグを手動で作成はしません。以下のコマンドで別リポジトリからまるごとタグ一覧をコピーしています。
gh label clone 対象のリポジトリ -f
ラベルつけを自動化していない理由
ラベルつけをするルールを作るのも守るのも手間で、手動でやるのがとくに苦ではなかったからです。
こだわりはないため自動化されてても全然いいと思います。
issue (チケット) を使っていない理由
PR に issue を紐づけておくと issue に書いた仕様やなぜやるのかといった背景に飛びやすいという点で便利です。
しかし、CoreBluetoothForUnity において仕様は Apple の CoreBluetooth のドキュメント貼れば良いので仕様を issue に書く必要がありませんでした。
優先度付けとかも手元のメモ帳で十分だったため issue を使っていません。
リリース告知後にバグが生じたり、議論が必要になるときには issue 使うつもりです。
参考
おわりに
GitHub Copilot 等でコミットメッセージを自動生成しても、そもそもコミット内容に含まれていない判断理由や参考文献等の生成は不可能でしょう。
そのため結局人間がコミットメッセージを適切に書く能力は今後も必要になるのかなと思っています。
コミットメッセージやプルリクの書き方で「理由」をかくことを意識していない方はぜひ試してみてください！