バッジポリシー

このドキュメントは、README のバッジ帯と、その動的データソースを公開するインフラストラクチャに関する正規のリファレンスです。 プロジェクトの README にあるすべてのバッジは、ここで規定する 3 つの形式のいずれかを通じて解決されます。 今後追加される新しいバッジは同じ形式に従うか、そうでなければレビューで却下されます。

1. 背景Copy Anchor Link

静的な https://img.shields.io/badge/X-Y-Z の URL はそれ自体では決して変化しないため、 プロジェクトの実際の状態から乖離していきます — release-vN-blue バッジは、 vN+1 が出荷されたずっと後も vN と表示し続けます。 そのためポリシーは、変動するすべての値に動的な形式を要求し、静的バッジの使用を、 めったに変化せず静的な形式が正直であるような少数の値（ライセンス、Python のターゲットバージョン）に限定します。

2. アーキテクチャCopy Anchor Link

4 つの形式で、プロジェクトのすべてのバッジをカバーします。

1. GitHub ネイティブのワークフローステータスバッジ。 ワークフローのバッジ URL は https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg という形をとり、 デフォルトブランチ上の最新の実行を反映します。 GitHub は、リポジトリの公開メタデータからバッジを提供します。
2. shields.io エンドポイントバッジ。 shields.io エンドポイントバッジは https://img.shields.io/endpoint?url=<published-json> という URL を解決し、 その JSON は shields.io のエンドポイントスキーマ（schemaVersion、label、 message、color）に準拠します。 公開される JSON は apothem.ahmedgad.com/badges/*.json にあり、 その内容は CI の実行が成功するたびに CI ワークフローによって生成されます。 エンドポイントバッジは、メトリクスをサードパーティの可変ストアではなく、プロジェクトが管理する公開の下に置きます。
3. shields.io 静的バッジ。 静的バッジは、リアクティブなデータソースを持たない https://img.shields.io/badge/<label>-<message>-<color> という形をとります。 本当にめったに変化しない値（ライセンス識別子、Python のターゲットバージョン）のために確保されています。
4. レジストリとスコアカードのバッジ。 サードパーティが、すでに保持している公開データから値を算出するバッジです。 npm レジストリ（バージョンとダウンロード数。shields.io がレンダリングします）と OpenSSF Scorecard API がこれにあたります。 これらについて、プロジェクトは何も公開しません。サードパーティがソースです。

プロジェクトのメトリクスをパブリック Gist で公開することは、設計上除外されています。 プロジェクトが管理するドメイン上の shields.io エンドポイントが、正規の代替手段です。

3. バッジごとの仕様Copy Anchor Link

この表は、README のバッジ帯を順番に列挙します。 最後の列は、リポジトリが公開されている間だけ画像が表示されるバッジを示します。 GitHub はプライベートリポジトリのワークフローバッジをサインイン済みのメンバーにのみ提供し、 Scorecard は公開リポジトリのみをスキャンします。

github.com 上の各バッジのリンク先（リリース、ワークフロー、ライセンスファイル、イシュー）は、 リポジトリが公開されている間だけ開くことができます。

badges ワークフローは、将来のバッジのために coverage.json、security.json、 supply-chain.json、docs.json のエンドポイントファイルも公開しています。 現在の README はそれらを表示していません。

CodeQL は、Python と Actions の面を解析する専用の .github/workflows/codeql.yml ワークフローとして実行されます。 ci.yml の security-scan ジョブは bandit のみを実行し、CodeQL の SARIF の公開は codeql.yml に任せています。 セキュリティバッジは、GitHub ネイティブのワークフローバッジではなく、badges ワークフローが公開するエンドポイント JSON を利用するため、 基盤となるスキャナーの構成が変わってもバッジは安定して保たれます。

4. JSON の公開メカニズムCopy Anchor Link

エンドポイント JSON は .github/workflows/badges.yml によって生成されます。 このワークフローは次のことを行います。

• ci ワークフローの完了後に workflow_run でトリガーされます（CI の実行なしで再公開するための、 手動の workflow_dispatch でもトリガーされます）。
• 完全な履歴のチェックアウト（fetch-depth: 0。深さ 1 のチェックアウトではタグ付きコミットに到達できず、 バッジは unreleased と表示されます）上で git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' を使って最新のリリースタグを解決し、 workflow_run イベントから親の CI の結論を解決します。
• 出力が shields.io のエンドポイントスキーマ（schemaVersion: 1 と、label、 message、color）に厳密に一致するよう、各 JSON を jq -n で生成します。
• 出力したすべての JSON を、アップロード前に jq -e で検証します。
• ディレクトリを badges という名前のワークフローアーティファクトとしてアップロードします。

apothem.ahmedgad.com/badges/ へのアーティファクトのデプロイは、 .github/workflows/publish-static-site.yml が担当します。 サイトのビルド中に、このワークフローは最新の成功した badges アーティファクトをダウンロードし、 site/dist/badges/ 配下にステージングします。 アーティファクトが存在しないか期限切れの場合でも、サイトはデプロイされ、 壊れた JSON を公開する代わりに、バッジアーティファクトの欠落をワークフローログに記録します。

5. メンテナンスプロトコルCopy Anchor Link

新しいバッジを追加するときは、まず形式を決めます。

• バッジが CI ワークフローの実行状態を反映する場合は、GitHub ネイティブの形式を優先します。 バッジの URL はワークフローファイルによって決まり、公開用のインフラストラクチャは必要ありません。
• バッジが時間とともに更新されるメトリクス（件数、割合、バージョン文字列、段階評価のラベル）を反映する場合は、 shields.io のエンドポイント形式を使用します。.github/workflows/badges.yml に、 既存の 5 つと並べて JSON 生成ステップを追加し、apothem.ahmedgad.com/badges/<name>.json のコンシューマー URL を README のバッジ帯に追加します。
• バッジが本当にめったに変化しない値（ライセンス、言語のターゲット、ガバナンスモード）を反映する場合は、 shields.io の静的形式を使用します。 バッジを追加するときに、このファイルのバッジごとの表に変更の頻度を記録します。

バッジを廃止するときは、まず README からバッジを削除し、次に badges ワークフローからその JSON 生成ステップを削除し、 最後に上記のバッジごとの表からその行を削除します。 README が、ワークフローの生成しない JSON アーティファクトを決して参照しないよう、削除はアトミックに行います。

6. 相互参照Copy Anchor Link

• GitHub ネイティブの CI バッジが実行状態を反映する CI ワークフロー: .github/workflows/ci.yml。
• エンドポイント JSON を公開する badges ワークフロー: .github/workflows/badges.yml。
• JSON を提供する静的サイトのドメイン: apothem.ahmedgad.com。
• shields.io のエンドポイントスキーマのリファレンス: https://shields.io/badges/endpoint-badge。