Badge-Richtlinie

Dieses Dokument ist die kanonische Referenz für die Badge-Leiste der README und die Infrastruktur, die ihre dynamischen 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 in der Prüfung abgelehnt.

1. Hintergrund

Statische https://img.shields.io/badge/X-Y-Z-URLs ändern sich nie von selbst, sodass sie sich vom realen Zustand des Projekts entfernen — 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, wo die statische Form ehrlich ist.

2. Architektur

Drei 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 letzten 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, wobei das 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 generiert. Endpoint-Badges halten Metriken unter projektkontrollierter Veröffentlichung statt in einem veränderlichen Drittanbieter-Speicher.
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 wirklich selten ändern (Lizenzkennung, Python-Zielversion).

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

3. Spezifikation pro Badge

CodeQL läuft als dedizierter .github/workflows/codeql.yml-Workflow, der die Python- und Actions-Oberflächen analysiert; der security-scan-Job in ci.yml führt nur bandit aus und überlässt die CodeQL-SARIF-Veröffentlichung codeql.yml. Der Sicherheits-Badge konsumiert 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. JSON-Veröffentlichungsmechanismus

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

• Wird über workflow_run ausgelöst, nachdem der ci-Workflow abgeschlossen ist (und über manuelles workflow_dispatch zur erneuten Veröffentlichung ohne CI-Lauf).
• Löst das neueste Tag aus git describe --tags --abbrev=0 und das übergeordnete CI-Ergebnis aus dem workflow_run-Ereignis auf.
• Generiert jedes JSON über jq -n, sodass die Ausgabe strikt dem shields.io-Endpoint-Schema entspricht (schemaVersion: 1 plus label, message, color).
• Validiert jedes ausgegebene JSON mit jq -e vor dem Hochladen.
• Lädt das Verzeichnis als Workflow-Artefakt namens badges hoch.

Die Bereitstellung der Artefakte unter apothem.ahmedgad.com/badges/ wird von .github/workflows/publish-static-site.yml übernommen. Während des Site-Builds lädt dieser Workflow das neueste erfolgreiche badges-Artefakt herunter und stellt es unter site/dist/badges/ bereit. Falls das Artefakt fehlt oder abgelaufen ist, wird die Site dennoch bereitgestellt und das fehlende Badge-Artefakt in den Workflow-Protokollen vermerkt, anstatt kaputtes JSON zu veröffentlichen.

5. Wartungsprotokoll

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

• Falls 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.
• Falls der Badge eine Metrik widerspiegelt (ein Zähler, ein Prozentsatz, eine Versionszeichenfolge, ein abgestuftes Etikett), die sich im Laufe der Zeit aktualisiert, verwenden Sie die shields.io-Endpoint-Form. Fügen Sie einen JSON-Generierungsschritt zu .github/workflows/badges.yml neben den bestehenden fünf hinzu und fügen Sie die Verbraucher-URL apothem.ahmedgad.com/badges/<name>.json zur Badge-Leiste der README hinzu.
• Falls der Badge einen Wert widerspiegelt, der sich wirklich selten ändert (Lizenz, Sprachziel, Governance-Modus), verwenden Sie die statische shields.io-Form. Dokumentieren Sie die Änderungskadenz in der Tabelle pro Badge in dieser Datei beim Hinzufügen des Badges.

Setzen Sie einen Badge außer Betrieb, indem Sie ihn zuerst aus der README entfernen, dann seinen JSON-Generierungsschritt aus dem badges-Workflow entfernen und schließlich seine Zeile aus der Tabelle pro Badge oben entfernen. Halten Sie die Löschung atomisch, damit die README niemals auf ein JSON-Artefakt verweist, das der Workflow nicht produziert.

6. Querverweise

• 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 Site, die die JSONs ausliefert: apothem.ahmedgad.com.
• Die Referenz für das shields.io-Endpoint-Schema: https://shields.io/badges/endpoint-badge.