複数OS向けのCLIダウンローダーにツールを足し、各バイナリを確かめる

## 足すツールが静的バイナリか確かめ、対応するOSを決める 直接実行できる静的バイナリとして配布されるコマンドラインツールを追加する場合に、このワークフローを使用してください。 システムパッケージ、コンテナイメージからの抽出、クラスタのアドオン、ランタイム管理型アプリケーションは、それぞれ専用のインストール経路へ振り分けてください。 コードを変更する前に、提案されたツールにコンパイル済みのリリースアセットがあることを確認してください。 インタープリター、パッケージマネージャー、インストーラースクリプト、または宣言されていないランタイム依存関係を必要とするパッケージは却下してください。 プロジェクトが広い一括変更を明示的に許可していない限り、貢献内容が単一のツールだけを変更することを確認してください。 プロジェクト固有の設計承認またはイシュー承認というゲートがある場合は、実装前にその承認を必須としてください。 リポジトリの命名規則に従い、対象を絞ったブランチを作成してください。 インストーラーのコマンド、ツールの対外表示名、アップストリームの所有者とリポジトリを特定してください。 インストーラーが対応すると想定されるすべてのプラットフォームの組み合わせを列挙してください。 プロジェクトが別のマトリクスを定義していない限り、次を基本対象とします。 - Linux（x86-64）。 - Linux（ARM64）。 - macOS（x86-64）。 - macOS（ARM64）。 - Windows（x86-64）。 インストーラーが32-bit x86またはARMv6を明示的に含んでいない限り、それらへの対応を表明してはいけません。 別のプラットフォームのアセットへ暗黙に置き換えず、利用できない組み合わせを記録してください。 ## コードを書く前に、OSとアーキテクチャごとの配布ファイル名を調べる ダウンロード用テンプレートを書く前に、アップストリームの最新安定版リリースを調査してください。 アップストリームの最新リリース用エンドポイントには、Locationヘッダーからバージョンタグを取得できるよう、リダイレクトだけを確認するリクエストを優先してください。 必要な結果がタグそのものである場合は、リダイレクト先へ移動してはいけません。 全件を表示したアセット一覧、またはその正確なタグに対応する別の信頼できるリリースページを調べてください。 同等の一般提供リリースメタデータを利用できる場合は、レート制限のあるAPIを使わないでください。 提供されているすべてのファイル名、アーカイブ形式、オペレーティングシステム、アーキテクチャを列挙してください。 amd64とx86_64、arm64とaarch64のような区別を含め、アップストリームの表記を正確に維持してください。 想定する対象ごとに、次を記録してください。 - アセットが存在するか。 - アセットの正確なファイル名。 - 該当する場合はアーカイブ形式。 - 異なる場合はアーカイブ内のバイナリ名。 - 互換性を変えるlibcまたはツールチェーンの派生版。 プロジェクトが対応し、選択が適切な場合は、muslなど移植可能な静的派生版を優先してください。 Rustのファイル名にunknownなどの語が含まれていても、アップストリームのリリースと一致する場合は有効として扱ってください。 収集したマトリクスを、テンプレート、テスト、プルリクエストの証拠に対する正本として使用してください。 ## 各OSに本当のダウンロードURLを対応付け、別のファイルで代用しない インストーラーで確立済みの定義構造を使ってツールを追加し、近くにある動作確認済みの例に従ってください。 必須の識別情報として、ツール名、アップストリームの所有者、リポジトリ、簡潔な説明を指定してください。 リリースアセット自体が実行ファイルである通常のバイナリには、バイナリファイル名のテンプレートを使ってください。 アセットの場所に独自のパス処理が必要な場合は、完全なURLのテンプレートを使ってください。 対応するすべてのオペレーティングシステムとアーキテクチャを、実際のアップストリームファイル名へ対応付けてください。 インストーラーのアーキテクチャ定数と、アップストリームのファイル名表記を分けてください。 ランタイムによるオペレーティングシステムの表現と一致する、明示的なWindows判定を使ってください。 対応するアーカイブ形式は、インストーラーの展開機能と一致していなければなりません。 一般に受け入れられる形式にはtar.gz、tgz、zip、bz2、tar.xzがあります。 利用できないプラットフォームの組み合わせでは、生成されたURLが対象なしを示す応答などで明確に失敗しなければなりません。 Linuxのアセット、別のアーキテクチャ、別のツールへ決してフォールバックしてはいけません。 接頭辞付きタグと数値版の両方を使う場合は特に、バージョンタグの変換を明示してください。 オペレーティングシステム、アーキテクチャ、名前、バージョン、所有者、リポジトリには既存のテンプレート変数を使ってください。 インストーラーがバージョン置換に対応している場合は、現在のバージョンを本番用定義へ直接書き込んではいけません。 テストに依存する前に、マトリクスの全行について最終URLをレビューしてください。 ## アーカイブの名前と、中にある実行ファイルの名前を分けて書く リリースアセット名と、アーカイブ内の実行ファイル名を別々の事実として扱ってください。 アーカイブにプラットフォーム接尾辞付きの実行ファイルが含まれる場合は、次の両方を定義してください。 - 拡張子を含むダウンロード対象アーカイブ名を指定するURLテンプレート。 - アーカイブ拡張子を除いた、展開後の実行ファイル名を指定するバイナリテンプレート。 拡張子付きのアーカイブファイル名を、バイナリテンプレートだけに指定してはいけません。 多くの展開処理では、展開されたファイルを探すためにバイナリテンプレートを使います。 このフィールドにアーカイブ拡張子があると、汎用ツール名へのフォールバックが発生する場合があります。 アーカイブにプラットフォーム固有のバイナリ名が含まれている場合、そのフォールバックは失敗します。 圧縮されていない通常の実行ファイルでは、一般にバイナリテンプレートだけで十分です。 ファイル名から推測せず、アーカイブを調べてこの区別を確認してください。 アーカイブが実行ファイルをディレクトリ接頭辞の内側へ配置しているか確認してください。 Windowsの実行ファイルで、対応付けと展開の両方にexe接尾辞が必要か確認してください。 チェックサム、署名、実行権限の処理を、既存のインストーラーと一致させてください。 展開処理がファイル不足を報告した場合は、次の三つの名前を比較してください。 - ダウンロードしたアセット。 - 展開されたアーカイブ内の項目。 - インストーラーが要求した名前。 広範なフォールバックを追加せず、定義の境界で対応付けを修正してください。 ## 版を固定して、全OS分のダウンロードURLをテストする 既存のダウンローダーテストの近くに、対象を絞った単体テストを追加してください。 固定したアップストリームバージョンを使い、URL生成を最新版に対して決してテストしないでください。 提供され、対応対象となるオペレーティングシステムとアーキテクチャの組み合わせごとにテストケースを作成してください。 所有者、リポジトリ、タグ、ファイル名、区切り文字、アーカイブ拡張子を含む、完全な期待URLをアサートしてください。 プラットフォーム固有のアーキテクチャ別名は、アップストリームが提供する表記どおりに含めてください。 特別なバージョン変換とWindows接尾辞がある場合はテストしてください。 利用できない組み合わせについて、フレームワークがそのようなケースに対応している場合は、インストーラーの意図した失敗動作をテストしてください。 テストを、変更されうるリリースメタデータから独立させてください。 実装前に収集したものと同じアセットマトリクスを使ってください。 最初に対象を絞ったパッケージテストを実行してください。 次に、該当する場合はプロジェクトが求めるより広いテスト対象を実行してください。 URLテストの合格が証明するのは文字列の組み立てだけであり、ダウンロードされたファイルが正しいバイナリであることまでは証明しません。 ## 全OS分のバイナリをダウンロードし、形式とアーキテクチャを確かめる クロスプラットフォーム検証の前にインストーラーをビルドしてください。 まず、上書きフラグを使わずに現在のプラットフォームのアセットをダウンロードしてください。 生成されたファイルを調べ、HTMLエラーページ、実行ファイルと誤認された圧縮データ、空のファイルを検出してください。 そのツールに対して、リポジトリのプラットフォームマトリクス検証スクリプトを実行してください。 テストを実行するマシンだけでなく、対応するすべての組み合わせを検証してください。 ファイル識別ツールまたは同等のバイナリパーサーを使い、形式とアーキテクチャを確認してください。 一般に期待される証拠には、次が含まれます。 - Linux x86-64は、64-bit ELF実行ファイルで、x86-64向け。 - Linux ARM64は、AArch64用の64-bit ELF実行ファイル。 - macOS x86-64は、64-bit Mach-O実行ファイルで、x86-64向け。 - macOS ARM64は、ARM64用の64-bit Mach-O実行ファイル。 - Windows x86-64は、PE32+コンソール実行ファイルで、x86-64向け。 テンプレートが誤ったプラットフォームをダウンロードする場合があるため、HTTP応答の成功だけでは不十分です。 内部の実行ファイルが誤ったアーキテクチャを対象にしている場合があるため、展開の成功だけでも不十分です。 失敗や警告を編集で隠さず、マトリクスの完全な結果を記録してください。 アップストリームで対象を利用できない場合は、インストーラーが互換性のないバイナリを渡すのではなく、その対象で失敗することを確認してください。 文書化または承認へ進む前に、すべての不一致を解消してください。 ## CLIの一覧表を作り直し、プルリクエストに確かめた結果を書く CLIカタログを再生成するために、リポジトリで文書化された手順に従ってください。 行を手作業で作らず、インストーラーからカタログを生成してください。 安全に置き換えるため必要な場合に限り、一時的なワークスペースファイルを使ってください。 カタログの開始マーカーと終了マーカーを正確に維持してください。 それらのマーカー間にある生成テーブルの内容と、関連するツール数だけを置き換えてください。 周辺の説明文や無関係な項目には手を加えないでください。 新しいツールが期待する説明とともに一度だけ現れることを確認してください。 更新後は一時生成ファイルを破棄してください。 次を明記したプルリクエストの説明を用意してください。 - 利用できるプラットフォームと利用できないプラットフォームの組み合わせ。 - 使用した信頼できるリリースタグと命名パターン。 - バイナリ形式を含む、プラットフォーム検証の完全な結果。 - 該当する場合は、必須のエンドツーエンドテストまたはより広いテストの結果。 すべてのコミットに、リポジトリで必須の署名表記があることを確認してください。 コマンドと固定バージョンを明記し、証拠を再現可能に保ってください。 不足するプラットフォーム、失敗したダウンロード、アーキテクチャの不一致を要約で隠してはいけません。 ## 変更をレビューし、ダウンロードや展開の失敗の原因を探す 適格性、対応付け、テスト、文書、証拠を別々のゲートとしてレビューしてください。 ツールが静的バイナリであり、変更が承認された範囲に限定されていることを確認してください。 必須の識別情報を確認し、有効なダウンロード対応付けが少なくとも一件存在することを確かめてください。 すべてのテンプレート分岐を、信頼できるアセットマトリクスと比較してください。 対応していない組み合わせが、別のプラットフォームのバイナリを受け取れないことを検証してください。 単体テストが固定バージョンを使い、対応するすべての対象を網羅していることを確認してください。 承認前に、表明するすべての対象についてバイナリ形式の証拠を必須としてください。 生成文書にそのツールが含まれ、境界マーカーが維持されていることを確認してください。 URLの不一致は、アップストリームの正確なファイル名とタグ変換を比較して調査してください。 誤ったアーキテクチャは、オペレーティングシステムとアーキテクチャの分岐を別々に追跡して調査してください。 展開の失敗は、アーカイブ名、アーカイブ内の項目、設定された内部バイナリ名を比較して調査してください。 ランタイムの失敗は、プロジェクトが実際に自己完結型の静的バイナリを提供しているか再検討して調査してください。 アップストリームにないアセットを、互換性のない代替物で回避してはいけません。 正当なアップストリームの不足は、プルリクエストに記録してください。 コード、テスト、ダウンロードしたアセット、文書、報告された証拠が一致する場合にのみ承認してください。