Release PR deploy note

codepatrol skillの指揮役から任されて、本番に出る前の修正が積まれたrelease pull requestに、デプロイの前後に人間がやる事をまとめた「Release PR deploy note」をコメントする。

自動修正では、修正のpull requestが速く積み上がる。DBのindexを作る、環境変数を足すといった注意書きは、個々のpull requestの概要欄に散らばり、デプロイする人間が気付けない。1箇所にまとめて、気付けるようにする。人間が、積まれた修正の内容をまとめて確かめる場所にもなる。

ファイル構成

{このSKILL.mdがあるディレクトリ}/
  SKILL.md                  ← この手順書
  DEPLOY-NOTE-TEMPLATE.md   ← noteのテンプレート

このskillを実行する時の前提

• ユーザーに質問できない。判断がつかない事は、最後の報告に書く
• コードは読まない。pull requestの概要欄とコメントから作る
• 書き込むのは、noteのコメントだけである。下書きの確認を取らずに投稿してよい。他のコメントや概要欄は編集しない
• GitHubに載る文章の書き方は、kuden:github skillに従う
• 対象のrelease pull requestは、指揮役の指示に従う

noteは1つのコメントを書き直し続ける

同じpull requestには、noteを1つだけ置く。既にnoteがあれば、それを書き直す。2つ目を投稿したり、追記のコメントを足したりしない。まとめが複数あると、どれを読めばよいのかが分からなくなる。

noteの冒頭には、どの時点までの何件を読んだかを書く。次に更新する時は、そこから前回の範囲を知り、増えたpull requestを読んで、既存の項目に足す。既に載っているpull requestも、前回の更新より後に概要欄が書き換わっていれば読み直し、項目を直す。積まれた修正から外れたpull requestの項目は消す。その上で全体を書き直す。何も変わっておらず、反映する人間の確認も無ければ、何もしない。

• 含まれるpull requestは、対象のpull requestのcommitから求める。概要欄の一覧は自動生成された物で、漏れる事がある
• 依存関係の更新botが作ったpull requestは読まない。概要欄に外部のrelease noteが入っていて、デプロイの作業は書かれていない
• 投稿の直前に、対象のpull requestと既存のnoteが、下書きを作った時点から変わっていないかを確かめる。pull requestが進んでいたら、増えた分を読み足す。noteが書き換わっていたら、最新のnoteに自分の変更を当て直す。他の担当が同じnoteを更新している事がある
• 人間がnoteに書き足した行は、消さずに残し、報告する

noteを書く

DEPLOY-NOTE-TEMPLATE.md を読み込み、その章立てに従う。

• 章は毎回全て、同じ順で出す。書く事が無い章も消さず、「なし」と書く。順序が固定されていると、読む人間が慣れる
• 各項目は、元のpull requestの番号から始める
• 概要欄に書かれたコマンドや定義は、要約せずにそのまま引用する。手で書き写さず、取得した概要欄から抜き出す
• 概要欄で済んだと書かれている作業には、「済み」と添える
• 概要欄の動作確認の項目のうち、実施されないままmergeされている物を載せる。人間の確認なしでmergeされた修正では、本番に出す前に人間が確かめる最後の機会になる
• checkboxは使わず、文章で書く。人間用のメモ欄も作らない

人間の確認を反映する

人間は、noteの項目を確かめたら、その事を個々のpull requestにコメントする。noteを更新するたびにそれを反映し、済んだ事を消していく。完了の印を並べるのではなく、残っている事だけが残るようにする。

• noteに載っている全てのpull requestと、対象のpull requestのコメントのうち、前回の反映より後に書かれた物と、編集された物を読む。確認が撤回されていれば、項目を戻す。どの時刻まで反映したかは、noteの末尾に書いて、次回の基準にする。今回新しくnoteに載せるpull requestは、コメントを全て読む。noteに載る前に確認されている事がある
• コメントに書かれた範囲だけを、確認済みにする。書かれていない項目は、当たり前に見えても残す。見落としなのか省略なのかを、noteを書く側が判断しない
• 一部が確認済みの項目は、誰が何を確認したかと、コメントへのリンクを書き、残りを書く。全部が確認済みの項目は、確認済みである事とリンクの1行にする
• 数えるのは、人間が確かめた事を述べているコメントである。自動修正の作業の中でAIが投稿したコメントは、人間のアカウントで投稿されていても数えない。逆に、AIの署名があるだけでは除外しない。開発者が、自分で確かめた事をAIに書かせている事がある

指揮役への報告

5行以内で書く。

• 対象のpull requestと、noteが対象にした時点、件数、前回から増えた件数
• 新しく投稿したのか、既存のnoteを書き直したのか。noteの場所
• 足した項目の要点と、反映した人間の確認
• 概要欄の動作確認の項目が、未実施のままmergeされているpull request
• 判断に迷った事と、人間の追記があった事