GitHubでの作法

pull requestを作成・更新・mergeする時、GitHubに載る文章を書く時は、以下の基準に従う。repoのドキュメントやPRテンプレートに別の定めがあれば、そちらに従う。文体はkuden:writing skillの基準に従う。

心得1. タイトルには、何を解決したかを書く

タイトルは、なぜ変えるのかと、この変更で何がどう変わるのかを、1文で書く。理由と、挙動がどう変わるかが書いてあれば、レビュアーはタイトルだけで妥当性の見当が付く。

• 実装の手順をなぞらない。そのPRで新しく作った関数名やファイルパスを並べたタイトルは、diffを読むまで意味が分からない
• 症状を消すとだけ書かない。「warningを消す」は握り潰しとも読め、変更の性質が伝わらない。「findOneAndUpdateのnew: trueはdeprecatedなのでreturnDocument: afterを使う」のように、理由と置き換えの中身を書く
• ユーザーに見えるbugの修正は、「<再現条件>で<症状>が起きる問題を修正」の形で書く。どう直したかは、概要欄の冒頭に置く
• 画面に関わる変更は、実装の語ではなく、影響する画面の名前で範囲を示す
• 既存のtoolに出力を1つ足すような小さな変更は、理由を付けず、既存のファイル名やfield名で短く書く。理由を付けて長くなるなら、理由は概要欄に回す
• commit messageの1行目も、ここまでの基準で書く
• 文末の時制や区切り方は、そのrepoのmerge済みのPRやcommitに合わせる

心得2. 概要欄は、変更の主目的から始め、動作確認方法で終える

• 何を直すPRなのかを最初に書く。bugに気付いた状況の説明は書いてよいが、本題の前に長く置かない。状況の説明が本題に見え、本題の説明を邪魔する
• 機能を構成する複数のステップをまとめたPRでは、ステップを操作や処理の流れの順にリスト記法で1行ずつ並べる。各行には、何を追加し、それで何ができるようになるかを書く。model・module・fileの実装単位で割らない。判定条件の中身や記録の形式のような詳細は、ステップのリストの後の節に置く
• 最後に動作確認方法を置き、レビュアーが手元で確かめる手順を書く。AIが済ませた検証は、それとは別の節に分ける

心得3. リンクが壊れない書き方をする

概要欄、コメント、commit message等、GitHubで表示される文章の全てに当てはまる。

• #1234 やURLの前後には、半角スペースを入れる。#1234で直した はリンクにならない。(https://example.com/日本語のページ)。 は、)。 までがURLに含まれる
• #数字 は、issueとPRの番号にだけ使う。Dependabot alertのように別の番号体系を持つ物は、フルURLで書く。#数字 で書くと、同じ番号の無関係なissueやPRへのリンクになる
• URLの日本語の部分は、percent-encodeせずに書く。encodeしたURLは、どのページへのリンクかを人間が読み取れない

心得4. 親子PRは、両方からリンクする

• 親PRの概要欄に ## 子PR の節を置き、子PRを作る度に - #1234 の形で足す
• 子PRの概要欄の1行目に、#1234 の子PRです と書く
• 親branchは、default branchに空のcommitを1つ積んで作り、親PRにする。default branchに無いcommitが1つも無いと、PRを作れない
• 子PRは親branchに向け、子PR同士は兄弟にする。ある子PRのbranchから次の子PRを作ると、先のPRのcommitがdiffに混ざる
• PRをどこに向けるかをユーザーに訊く時は、branch名ではなくPRの関係で訊く。「feature-x からbranchを切るか」ではなく、「#1234 の子PRにするか、mainに向けたPRにするか」と訊き、本番に載る時期のような帰結を添える

心得5. squash and mergeのcommit messageは、概要欄を要約して書く

GitHubでsquash and mergeすると、commit messageの1行目はPRのタイトルになり、本文の既定値は個別commitのmessageの連結になる。本文は既定値を使わず、概要欄を要約して書く。

• 個別commitのmessageを本文に残さない。「Aを実装」「Bを実装」「Aを廃止」の3 commitを連結すると、Aを実装したように読める
• 本文には、タイトルに無い変更内容や理由を簡潔に書く。タイトルで足りるなら本文は書かない
• 機能を構成するステップを概要欄に並べたPRでは、本文もそのステップを同じ順にリスト記法で書く。判定条件の中身のような詳細を本文にしない
• Co-Authored-ByやClaude Sessionのような、AIのattribution行を書かない