Politique des badges

Ce document est la référence canonique pour la bande de badges du README et l'infrastructure qui publie ses sources de données dynamiques. Chaque badge du README du projet se résout via l'une des trois formes spécifiées ici ; les nouveaux badges ajoutés à l'avenir suivent les mêmes formes ou sont rejetés en revue.

1. ContexteCopy Anchor Link

Les URL statiques https://img.shields.io/badge/X-Y-Z ne changent jamais d'elles-mêmes, de sorte qu'elles s'écartent de l'état réel du projet — un badge release-vN-blue continue d'afficher vN longtemps après la sortie de vN+1. La politique exige donc des formes dynamiques pour chaque valeur qui évolue, et réserve les badges statiques au petit ensemble de valeurs (licence, version cible de Python) qui changent rarement, pour lesquelles la forme statique est honnête.

2. ArchitectureCopy Anchor Link

Quatre formes couvrent chaque badge du projet :

1. Badges de statut de flux de travail natifs GitHub. L'URL de badge d'un flux de travail a la forme https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg et reflète la dernière exécution sur la branche par défaut. GitHub sert le badge à partir des métadonnées publiques du dépôt.
2. Badges d'endpoint shields.io. Un badge d'endpoint shields.io résout une URL https://img.shields.io/endpoint?url=<published-json> dont le JSON est conforme au schéma d'endpoint shields.io (schemaVersion, label, message, color). Le JSON publié se trouve à apothem.ahmedgad.com/badges/*.json ; son contenu est généré par un flux de travail CI à chaque exécution CI réussie. Les badges d'endpoint maintiennent les métriques sous une publication contrôlée par le projet plutôt que dans un magasin mutable tiers.
3. Badges statiques shields.io. Un badge statique a la forme https://img.shields.io/badge/<label>-<message>-<color> sans source de données réactive. Réservés aux valeurs qui changent véritablement rarement (identifiant de licence, version cible de Python).
4. Badges de registre et de scorecard. Un badge dont la valeur est calculée par un tiers à partir de données publiques qu'il détient déjà : le registre npm (version et téléchargements, rendus par shields.io) et l'API OpenSSF Scorecard. Le projet ne publie rien pour ces badges ; le tiers en est la source.

La publication des métriques du projet via des Gists publics est exclue par conception. Les endpoints shields.io sur le domaine contrôlé par le projet en sont le substitut canonique.

3. Spécification par badgeCopy Anchor Link

Le tableau liste la bande de badges du README dans l'ordre. La dernière colonne signale les badges dont l'image ne s'affiche que tant que le dépôt est public : GitHub ne sert le badge de flux de travail d'un dépôt privé qu'aux membres connectés, et Scorecard n'analyse que les dépôts publics.

La cible du lien de chaque badge sur github.com (publications, flux de travail, fichier de licence, issues) ne s'ouvre que tant que le dépôt est public.

Le flux de travail des badges publie aussi les fichiers d'endpoint coverage.json, security.json, supply-chain.json et docs.json pour de futurs badges ; le README ne les affiche pas aujourd'hui.

CodeQL s'exécute comme un flux de travail dédié .github/workflows/codeql.yml qui analyse les surfaces Python et Actions ; le job security-scan de ci.yml n'exécute que bandit, et laisse la publication SARIF de CodeQL à codeql.yml. Le badge de sécurité consomme le JSON d'endpoint publié par le flux de travail des badges plutôt qu'un badge de flux de travail natif GitHub, ce qui garde le badge stable quelle que soit la topologie du scanner sous-jacent.

4. Mécanisme de publication du JSONCopy Anchor Link

Les JSON d'endpoint sont produits par .github/workflows/badges.yml. Le flux de travail :

• Se déclenche sur workflow_run après l'achèvement du flux de travail ci (et sur un workflow_dispatch manuel pour une republication sans exécution CI).
• Résout la dernière étiquette de publication avec git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' sur un checkout à historique complet (fetch-depth: 0 ; sur un checkout de profondeur 1, aucun commit étiqueté n'est atteignable et le badge affiche unreleased), et la conclusion de la CI parente depuis l'événement workflow_run.
• Génère chaque JSON via jq -n afin que la sortie corresponde strictement au schéma d'endpoint shields.io (schemaVersion: 1, plus label, message, color).
• Valide chaque JSON émis avec jq -e avant le téléversement.
• Téléverse le répertoire en tant qu'artefact de flux de travail nommé badges.

Le déploiement des artefacts vers apothem.ahmedgad.com/badges/ est géré par .github/workflows/publish-static-site.yml. Pendant la construction du site, ce flux de travail télécharge le dernier artefact badges réussi et le place sous site/dist/badges/. Si l'artefact est absent ou expiré, le site se déploie quand même et consigne l'artefact de badge manquant dans les journaux du flux de travail au lieu de publier du JSON cassé.

5. Protocole de maintenanceCopy Anchor Link

Ajoutez un nouveau badge en décidant d'abord de sa forme :

• Si le badge reflète l'état d'exécution d'un flux de travail CI, préférez la forme native GitHub. L'URL du badge est fixée par le fichier de flux de travail ; aucune infrastructure de publication n'est nécessaire.
• Si le badge reflète une métrique (un décompte, un pourcentage, une chaîne de version, un libellé gradué) qui se met à jour au fil du temps, utilisez la forme d'endpoint shields.io. Ajoutez une étape de génération de JSON à .github/workflows/badges.yml à côté des cinq existantes et ajoutez l'URL consommatrice apothem.ahmedgad.com/badges/<name>.json à la bande de badges du README.
• Si le badge reflète une valeur qui change véritablement rarement (licence, langage cible, mode de gouvernance), utilisez la forme statique shields.io. Documentez la cadence de changement dans le tableau par badge de ce fichier lors de l'ajout du badge.

Retirez un badge en le supprimant d'abord du README, puis en supprimant son étape de génération de JSON du flux de travail des badges, et enfin en supprimant sa ligne du tableau par badge ci-dessus. Gardez la suppression atomique afin que le README ne référence jamais un artefact JSON que le flux de travail ne produit pas.

6. Références croiséesCopy Anchor Link

• Le flux de travail CI dont le badge CI natif GitHub reflète l'état d'exécution : .github/workflows/ci.yml.
• Le flux de travail des badges qui publie les JSON d'endpoint : .github/workflows/badges.yml.
• Le domaine du site statique qui sert les JSON : apothem.ahmedgad.com.
• La référence du schéma d'endpoint shields.io : https://shields.io/badges/endpoint-badge.