setup-template

setup-template

masseater/typescript-template から作ったリポジトリを、テンプレートに揃える。GitHub 側の設定は gh で揃え、中身の移行が完了しているかは、テンプレートの骨格と突き合わせて確かめる。対象リポジトリを REPO=<owner>/<name> とする。

• 設定はすべて gh で行う
• どの手順も、同じ値で何度実行しても結果が変わらない
• それ以外のリポジトリで使うときは、作業を始める前に、どの手順を適用するかをユーザーに確認する
• 基準にするのは、テンプレートが持ち続けている骨格である。テンプレートの新しいリリースで増えた要素は、欠けとして扱わない
• 各要素は、入っているか、効いているか、古い形や重複が残っていないかの 3 点で見る
• 判定には、コマンドの出力やファイルの実物を根拠として添える
• 対象外の要素には、リポジトリの現実から言える理由を書く
• 検査では直さない。欠けは一覧として渡す。直しながら検査すると、判定が直しの結果に塗り替わる
• 検査や lint を緩めて緑にした形跡は、欠けとして扱う

この skill が必要な理由と達成したい状態

この skill が必要な理由は、テンプレートから作ったリポジトリに、コードとワークフローは引き継がれても、GitHub 側の設定とアプリ名が引き継がれないことにある。secrets、Actions の権限、ルールセットがそれにあたる。ワークフローのファイルは揃っているので、設定が抜けていてもファイルを見ただけでは分からない。抜けたまま動く自動化は、失敗するか、何もしないまま終わる。どちらにせよ、誰も気づかない。

中身も同じである。移行の欠けは失敗として現れない。hook が 1 つ足りなくても、古い設定が隣に残っても、入っている検査の範囲では、ビルドもテストも verify も通る。欠けは気づかれずに残り、取り残しは効かないまま残る。報告には「移行しました」しか出てこない。テンプレートは動くアプリの土台も持っているので、移行の目標は「アプリが動く」ことに寄る。そのぶん、動かすのに要らない骨格から先に抜け落ちる。リポジトリは欠けを教えてくれないので、テンプレートの骨格から逆向きに突き合わせないと、未完了は見つからない。

この skill で達成したい状態は、作った直後から、テンプレートと同じ自動化と保護が GitHub 側でも中身でも効いていて、その状態を要素ごとに実物の出力で言い切れていることである。

検査の基準

typescript-template も読むこと。

• 骨格の一覧は references にある。今のタスクの並び、hook の中身、ワークフローの条件のような細部は、手元のテンプレートの実物で確かめる。一覧を写しとして使わない
• テンプレートの新しいリリースで増えた要素は、欠けにしない。それは移行の欠けではなく、更新の未取り込みである。取り込みは template-release の仕組みが案内する。混ぜると、未完了なのか、ただ古いだけなのかが判定から読めなくなる
• 対象外の要素には理由を書く。「アプリを持たない」「デプロイしない」のように、リポジトリの現実から言えることだけを理由にする。理由の書けない対象外は欠けである

判定の作り方

• 入りは、ファイルと依存が実在するかで見る
• 効きは、動かす仕組みが繋がっていて、実際に走るかで見る。設定ファイルにあるだけの hook や、このリポジトリでは決して動かない条件は、効いていない
• 残りは、置き換えの済んだ古い仕組みが残っていないか、同じ役割の設定が二重になっていないかで見る
• 古い形でも働いているものは、欠けにしない。欠けと言えるのは、無いことで何かが壊れるか、静かに無効になるものだけである。形の新しさはテンプレートの更新の領分なので、混ぜると本当の欠けが埋もれる
• 根拠は実物にする。ファイルを開き、コマンドを実行する。poteto-principles の prove-it-works に従い、「ありそう」は判定にしない
• vp install と vp run verify を実行する。verify が落ちたら、落ちたタスクとその出力を最初の欠けとして扱う
• 判定は「移行完了」か「未完了」の 2 つにする。未完了には、要素、欠けの中身、根拠のコマンドと出力を添える
• 検査のタスクや厳しさを緩めて緑にした形跡は、それ自体を欠けにする。タスクの削除、severity や ignorePatterns の緩和、無視コメントの増加がそれにあたる。緩んでいるかもしれない検査は、ほかの判定の基準に使えないからである

用途

次を読むこと。

• setup。GitHub 側の設定を gh で揃える
• check。移行の完了を判定する