Badge-Richtlinie

Dieses Dokument ist die kanonische Referenz für die Badge-Leiste der README und die Infrastruktur, die deren dynamische Datenquellen veröffentlicht. Jeder Badge in der README des Projekts wird über eine der drei hier festgelegten Formen aufgelöst; künftig hinzugefügte neue Badges folgen denselben Formen oder werden im Review abgelehnt.

1. HintergrundCopy Anchor Link

Statische https://img.shields.io/badge/X-Y-Z-URLs ändern sich niemals von selbst und entfernen sich daher vom tatsächlichen Zustand des Projekts — ein release-vN-blue-Badge zeigt noch lange vN an, nachdem vN+1 ausgeliefert wurde. Die Richtlinie verlangt daher dynamische Formen für jeden Wert, der sich bewegt, und reserviert statische Badges für die kleine Menge von Werten (Lizenz, Python-Zielversion), die sich selten ändern und bei denen die statische Form ehrlich ist.

2. ArchitekturCopy Anchor Link

Vier Formen decken jeden Badge des Projekts ab:

1. GitHub-native Workflow-Status-Badges. Die Badge-URL eines Workflows hat die Form https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg und spiegelt den neuesten Lauf auf dem Standard-Branch wider. GitHub liefert den Badge aus den öffentlichen Metadaten des Repositorys aus.
2. shields.io-Endpoint-Badges. Ein shields.io-Endpoint-Badge löst eine https://img.shields.io/endpoint?url=<published-json>-URL auf, deren JSON dem shields.io-Endpoint-Schema entspricht (schemaVersion, label, message, color). Das veröffentlichte JSON liegt unter apothem.ahmedgad.com/badges/*.json; sein Inhalt wird von einem CI-Workflow bei jedem erfolgreichen CI-Lauf erzeugt. Endpoint-Badges halten Metriken unter projektkontrollierter Veröffentlichung statt in einem veränderlichen Speicher eines Drittanbieters.
3. Statische shields.io-Badges. Ein statischer Badge hat die Form https://img.shields.io/badge/<label>-<message>-<color> ohne reaktive Datenquelle. Reserviert für Werte, die sich tatsächlich selten ändern (Lizenzkennung, Python-Zielversion).
4. Registry- und Scorecard-Badges. Ein Badge, dessen Wert ein Dritter aus öffentlichen Daten berechnet, die er bereits vorhält: die npm-Registry (Version und Downloads, gerendert von shields.io) und die OpenSSF Scorecard API. Das Projekt veröffentlicht für diese nichts; der Dritte ist die Quelle.

Die Veröffentlichung von Projektmetriken über öffentliche Gists ist bewusst ausgeschlossen. shields.io-Endpoints über die projektkontrollierte Domain sind der kanonische Ersatz.

3. Spezifikation je BadgeCopy Anchor Link

Die Tabelle listet die Badge-Leiste der README in ihrer Reihenfolge. Die letzte Spalte kennzeichnet die Badges, deren Bild nur gerendert wird, solange das Repository öffentlich ist: GitHub liefert einen Workflow-Badge für ein privates Repository nur an angemeldete Mitglieder aus, und Scorecard scannt nur öffentliche Repositorys.

Das Linkziel jedes Badges auf github.com (Releases, der Workflow, die Lizenzdatei, Issues) öffnet sich nur, solange das Repository öffentlich ist.

Der badges-Workflow veröffentlicht außerdem die Endpoint-Dateien coverage.json, security.json, supply-chain.json und docs.json für künftige Badges; die README zeigt sie derzeit nicht an.

CodeQL läuft als dedizierter Workflow .github/workflows/codeql.yml, der die Python- und Actions-Oberflächen analysiert; der Job security-scan in ci.yml führt nur bandit aus und überlässt die Veröffentlichung der CodeQL-SARIF codeql.yml. Der Sicherheits-Badge nutzt das vom badges-Workflow veröffentlichte Endpoint-JSON statt eines GitHub-nativen Workflow-Badges und bleibt so über die zugrunde liegende Scanner-Topologie hinweg stabil.

4. Mechanismus der JSON-VeröffentlichungCopy Anchor Link

Die Endpoint-JSONs werden von .github/workflows/badges.yml erzeugt. Der Workflow:

• Wird über workflow_run ausgelöst, nachdem der Workflow ci abgeschlossen ist (und über ein manuelles workflow_dispatch zur erneuten Veröffentlichung ohne CI-Lauf).
• Ermittelt das neueste Release-Tag mit git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' auf einem Checkout mit vollständigem Verlauf (fetch-depth: 0; auf einem Checkout der Tiefe 1 ist kein getaggter Commit erreichbar, und der Badge zeigt unreleased) sowie das Ergebnis des übergeordneten CI-Laufs aus dem workflow_run-Ereignis.
• Erzeugt jedes JSON über jq -n, sodass die Ausgabe strikt dem shields.io-Endpoint-Schema entspricht (schemaVersion: 1 sowie label, message, color).
• Validiert jedes ausgegebene JSON vor dem Hochladen mit jq -e.
• Lädt das Verzeichnis als Workflow-Artefakt mit dem Namen badges hoch.

Das Deployment der Artefakte nach apothem.ahmedgad.com/badges/ übernimmt .github/workflows/publish-static-site.yml. Während des Builds der Website lädt dieser Workflow das neueste erfolgreiche badges-Artefakt herunter und legt es unter site/dist/badges/ bereit. Fehlt das Artefakt oder ist es abgelaufen, wird die Website dennoch deployt, und das fehlende Badge-Artefakt wird in den Workflow-Protokollen vermerkt, statt fehlerhaftes JSON zu veröffentlichen.

5. WartungsprotokollCopy Anchor Link

Fügen Sie einen neuen Badge hinzu, indem Sie zuerst die Form festlegen:

• Wenn der Badge den Laufzustand eines CI-Workflows widerspiegelt, bevorzugen Sie die GitHub-native Form. Die URL des Badges ist durch die Workflow-Datei festgelegt; es ist keine Veröffentlichungsinfrastruktur erforderlich.
• Wenn der Badge eine Metrik widerspiegelt (eine Anzahl, einen Prozentsatz, eine Versionszeichenkette, eine abgestufte Bezeichnung), die sich im Lauf der Zeit ändert, verwenden Sie die shields.io-Endpoint-Form. Fügen Sie .github/workflows/badges.yml neben den bestehenden fünf einen Schritt zur JSON-Erzeugung hinzu, und fügen Sie die Konsumenten-URL apothem.ahmedgad.com/badges/<name>.json zur Badge-Leiste der README hinzu.
• Wenn der Badge einen Wert widerspiegelt, der sich tatsächlich selten ändert (Lizenz, Zielsprache, Governance-Modus), verwenden Sie die statische shields.io-Form. Dokumentieren Sie beim Hinzufügen des Badges den Änderungsrhythmus in der Tabelle je Badge in dieser Datei.

Nehmen Sie einen Badge außer Betrieb, indem Sie ihn zuerst aus der README entfernen, dann seinen Schritt zur JSON-Erzeugung aus dem badges-Workflow und schließlich seine Zeile aus der obigen Tabelle je Badge. Halten Sie die Löschung atomar, damit die README niemals auf ein JSON-Artefakt verweist, das der Workflow nicht erzeugt.

6. QuerverweiseCopy Anchor Link

• Der CI-Workflow, dessen Laufzustand der GitHub-native CI-Badge widerspiegelt: .github/workflows/ci.yml.
• Der badges-Workflow, der die Endpoint-JSONs veröffentlicht: .github/workflows/badges.yml.
• Die Domain der statischen Website, die die JSONs ausliefert: apothem.ahmedgad.com.
• Die Referenz für das shields.io-Endpoint-Schema: https://shields.io/badges/endpoint-badge.