GitHubでの作法

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

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

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

• 実装の手順をなぞらない。そのPRで新しく作った関数名やファイルパスを並べたタイトルは、diffを読むまで意味が分からない
• 症状を消すとだけ書かない。「warningを消す」は握り潰しとも読め、変更の性質が伝わらない。「findOneAndUpdateのnew: trueはdeprecatedなのでreturnDocument: afterを使う」のように、理由と置き換えの中身を書く
• 自分達が仕様を決めた物の挙動が理由なら、「〜に対応した」と自分達の変更として書く。「XがYするので」と原因を外に置く形は、Xが自分達で変えられない物の時だけに使う。自分達のコントロール範囲内の事柄を原因に置くと、範囲外のどうしようもない事のように読め、前提条件を誤読させる
• 実装の条件を網羅するより、解決する問題を具体的に書く。効果の大半を占める条件を書き、残りの条件は概要欄に任せる
• ユーザーに見えるbugの修正は、「<再現条件>で<症状>が起きる問題を修正」の形で書く。どう直したかは、概要欄の冒頭に置く
• optionを足す変更は、「<何を変えるoptionか> <option名>を追加」の形で書く。効く範囲の限定や既定値は、概要欄に書く
• 機能の変更は、注釈が無ければ、その機能が主に使われる画面での話として読まれる。それ以外の画面の挙動を変える時だけ、画面の名前で範囲を示す。画面の名前は、実装の語ではなく、ユーザーが見る名前で書く
• 選択の余地が無い付帯条件は書かない。ブラウザが音声トラック付きの動画をmuted属性を付けずに自動再生する事を許さないので無音にした、のような、技術的な制約で決まる条件がこれに当たる
• toolやmoduleの領域を示す時は、「<tool名> - 」か「<tool名>にて」と書く。「<tool名>で〜する」は、そのtoolを使って〜するとも読める
• 既存のtoolに出力を1つ足すような小さな変更は、理由を付けず、既存のファイル名やfield名で短く書く。理由を付けて長くなるなら、理由は概要欄に回す
• commit messageの1行目も、ここまでの基準で書く
• 文末の時制や区切り方は、そのrepoのmerge済みのPRやcommitに合わせる

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

• 何を直すPRなのかを最初に書く。冒頭には、見出しを付けず、指示元や関連ページのURLと、位置づけを示す1〜2文を置く。bugに気付いた状況の説明を本題の前に長く置くと、状況の説明が本題に見え、本題の説明を邪魔する。コード全体に効く欠陥なら、気付いた特定の実行の話で始めず、経緯は起点へのリンクで足りる
• 機能を構成する複数のステップをまとめたPRでは、ステップを操作や処理の流れの順にリスト記法で1行ずつ並べる。各行には、何を追加し、それで何ができるようになるかを書く。model・module・fileの実装単位で割らない。判定条件の中身や記録の形式のような詳細は、ステップのリストの後の節に置く
• 変更内容の節は「## 変更」、範囲外の節は「## このPRでやらない事」、確認手順の節は「## 動作確認方法」と書く。「## このPRでやる事」「## やらない事」とは書かない。「やる事」はTODOの語感で、PRは既にやった変更を説明する物である。範囲外の節に「このPRで」を付けないと、機能として永久にやらないように読める
• 最後に動作確認方法を置き、レビュアーが手元で確かめる手順を書く。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にするか」と訊き、本番に載る時期のような帰結を添える
• 親PRの概要欄は、親PRをmergeするまでに、mergeする実装に合わせて書き直す。作成時の概要欄は「詳細は子PRで詰める」の仮置きになりがちで、子PRのmergeで実装が変わると古くなる

心得5. タイトル・概要欄・コメントは、直前に最新版を取得してから書き換える

タイトル・概要欄・コメントのように人間も編集する共有テキストは、他の人が並行して編集している前提で扱う。

• 書き換える直前に最新版を取得し、自分が元にした版から変わっていない事を確かめる。変わっていれば、最新版の上に自分の変更を当て直す
• 元に戻す時は、編集履歴で取り消す変更を確かめ、最新版からその変更だけを取り消す

心得6. レビュー指摘には、現在のコードを読んでから対応する

指摘が付いた時点のdiffではなく、現在のファイルの該当箇所を読み、指摘がまだ当てはまるかを確かめてから直す。

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

squash and mergeでは、commit messageの1行目を指定せず、GitHubの既定値に任せる。本文は既定値を使わず、概要欄を要約して書く。

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