开发与测试
github
GitHubでpull requestを作り、文章を書く時の心得。PRのタイトルと概要欄の書き方、リンクが壊れない書き方、sub pull requestの組み方を定める。 pull requestを作成・更新する時、GitHubに載る文章を書く時に読み込む。
shokai · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add shokai/agent-skills --skill github技能说明
name: github description: >- GitHubでpull requestを作り、文章を書く時の心得。PRのタイトルと概要欄の書き方、リンクが壊れない書き方、sub pull requestの組み方を定める。 pull requestを作成・更新する時、GitHubに載る文章を書く時に読み込む。
GitHubでの作法
pull requestを作成・更新する時、GitHubに載る文章を書く時は、以下の基準に従う。repoのドキュメントやPRテンプレートに別の定めがあれば、そちらに従う。
心得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に気付いた状況の説明は書いてよいが、本題の前に長く置かない。状況の説明が本題に見え、本題の説明を邪魔する
- 最後に動作確認方法を置き、レビュアーが手元で確かめる手順を書く。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. sub pull requestは、親子の両方からリンクする
- 親PRの概要欄に
## sub pull requestの節を置き、sub PRを作る度に- #1234の形で足す - sub PRの概要欄の1行目に、
#1234 に向けたsub pull requestですと書く - 親branchは、default branchに空のcommitを1つ積んで作り、親PRにする。default branchに無いcommitが1つも無いと、PRを作れない
- sub PR同士は兄弟にする。あるsub PRのbranchから次のsub PRを作ると、先のPRのcommitがdiffに混ざる
- PRをどこに向けるかをユーザーに訊く時は、branch名ではなくPRの関係で訊く。「
feature-xからbranchを切るか」ではなく、「#1234 に向けたsub PRにするか、mainに向けたPRにするか」と訊き、本番に載る時期のような帰結を添える