0080 — Notations externes & badges README : doctrine d'affichage

Statut

Accepted (2026-06-16). Application directe du biais adoptif borné (ADR 0061) et de l’honnêteté des preuves (ADR 0052) au cas particulier des badges de README. Fondé par les deux passages d’audit du 2026-06-16 (notations cyber, notations & normes externes), dont il exécute le plan de remédiation « rangée de badges ».

Contexte

Les deux passages d’audit du 2026-06-16 ont confronté le dépôt à des référentiels externes notés ou normalisés (OpenSSF Scorecard & Best Practices Badge, CIS, FAIR, SemVer, Keep a Changelog, Conventional Commits, OpenGitOps, WCAG, REUSE…). Verdict commun : le dépôt est déjà fortement aligné mais rarement nommé. La finalité concrète retenue est une rangée de badges au README, qui ne comptait qu’un seul badge (DOI Zenodo).

Mais un badge n’est pas neutre. Deux travers guettent, symétriques à ceux que borne l’ADR 0061 :

• Le badge décoratif — afficher « OpenSSF passing » alors que rien n’est câblé, « build passing » sans CI, un score figé recopié à la main. C’est le « badge pour le badge » : il ment sur l’état, et contredit frontalement l’honnêteté des preuves (ADR 0052 : un résultat n’a de valeur que reproductible et vrai).
• L’inflation illisible — empiler vingt badges en vrac jusqu’à ce que la rangée ne porte plus aucun signal. Sans ordre, le lecteur ne voit pas quelles familles le dépôt revendique.

Sans doctrine, chaque ajout de badge rejouerait l’arbitrage « honnête ? pertinent ? où le mettre ? ». Il faut une règle.

Décision

Un badge n’est affiché que s’il reflète un état VRAI et vérifiable, et la rangée est ORDONNÉE par thématique. Trois règles.

1. Honnêteté — n’afficher que ce qui mesure quelque chose de vrai

Un badge est admissible si et seulement si l’une des conditions tient :

• Dynamique & câblé : il est servi par un outil réellement branché qui recalcule l’état (badge d’état d’un workflow GitHub Actions, badge OpenSSF Scorecard alimenté par scorecard.yml, badge Best Practices alimenté par le projet bestpractices.dev). L’état affiché est l’état réel, à tout instant.
• Statique mais factuel & stable : il pointe une vérité non datée et invariante du dépôt (licence MIT ; conformité à une spec de convention — SemVer, Keep a Changelog, Conventional Commits — réellement appliquée et outillée ; DOI). Un badge statique ne porte jamais un score ou un palier susceptible de bouger (pas de « coverage 87 % » figé à la main).

Conséquence opératoire : un référentiel « noté » dont l’outil n’est pas encore câblé n’a pas de badge — il reste au plan de remédiation du passage d’audit jusqu’à son câblage. On ne pose pas un badge « en attendant ».

2. Pertinence — pas de badge pour un référentiel écarté

Un référentiel examiné et écarté par un passage d’audit (DORA sans prod, ISO 27001/25010 hors périmètre, SRE error-budget non mesurable sur réseau isolé) n’obtient pas de badge, même s’il en existe un upstream. Son absence est un choix tracé (le passage d’audit le dit), pas un oubli. C’est le critère 2 de l’ADR 0061 appliqué à l’affichage : le badge doit apporter un signal net, pas du bruit.

3. Lisibilité — la rangée est ordonnée par thématique

Les badges sont groupés par famille, dans cet ordre (du plus identitaire au plus opérationnel), un groupe par ligne logique :

1. Identité & licence — DOI, License.
2. Conventions & versionnement — Conventional Commits, SemVer, Keep a Changelog.
3. Qualité & CI — état CI (ci.yml).
4. Sécurité & supply-chain — OpenSSF Scorecard (scorecard.yml) ; Best Practices Badge à venir (action hors dépôt sur bestpractices.dev).
5. Science ouverte & accessibilité — réservée : un badge a11y est prévu mais son câblage a été différé (outil pa11y-ci obsolète, gain net insuffisant — cf. passage d’audit & issue #368). La famille existe dans l’ordre pour quand un outil à jour sera retenu.

L’ordre est une règle, pas une esthétique : il rend visible quelles cultures le dépôt revendique (ADR 0062), dans le même esprit que la vue « par culture d’ingénierie » de bonnes-pratiques.md. Un nouveau badge se range dans sa famille, jamais en fin de liste par commodité. Un commentaire HTML dans le README rappelle la règle au point d’insertion.

Conséquences

• Une rangée qui ne ment pas : tout badge affiché est soit recalculé en continu, soit une vérité stable. Le lecteur peut s’y fier — c’est l’honnêteté des preuves portée jusqu’à la vitrine.
• Un plan de remédiation lisible : les badges « notés » non encore câblés ont une place nommée (le passage d’audit) et un critère de clôture (« le badge devient honnête quand l’outil tourne »). L’écart entre l’ambition et l’état est visible et borné, pas masqué.
• Une rangée qui se lit : groupée par thématique, elle dit les familles revendiquées. L’ajout d’un badge est trivial (le ranger dans sa famille) et ne rouvre pas l’arbitrage de fond.
• Pas de blanc-seing : ce n’est pas « tout référentiel a son badge ». La pertinence (règle 2) écarte ce qui ne mesure rien de vrai ici — fidèle au fait que le dépôt n’est pas un produit en prod permanente (ADR 0023).
• Prix à payer : un jugement humain reste requis à chaque badge candidat (« dynamique ou stable ? quelle famille ? écarté ou en attente ? »). La règle cadre, elle n’automatise pas — comme l’ADR 0061 dont elle dérive.

Mise à jour 2026-06-19 — retrait du badge Best Practices

Le badge OpenSSF Best Practices (rangé en règle 3 §4, « Sécurité & supply-chain — à venir ») est retiré du README, et la famille n’expose plus qu’OpenSSF Scorecard, mis en avant sous le titre (badge le plus structurant, recalculé en continu par scorecard.yml).

Motif — application de la règle 1 (honnêteté), pas un revirement : le Best Practices Badge n’est pas un état mesuré par un outil branché, c’est un questionnaire d’auto-déclaration (le mainteneur répond lui-même au formulaire bestpractices.dev). Il « note » des affirmations, pas une vérité vérifiable du dépôt — exactement le badge décoratif que la règle 1 borne. La règle 1 le citait comme « dynamique & câblé » par assimilation ; ce passage corrige cette lecture : un score auto-déclaré n’est pas un état dynamique au sens où l’est un workflow ou Scorecard. Le retirer renforce la doctrine (n’afficher que ce qui mesure du vrai), il ne la contredit pas.

Conséquence : en sécurité, la rangée ne porte plus que des signaux recalculés en continu. La page d’accueil du site vit désormais dans docs/index.md ; le README racine est du Markdown GitHub pur (plus de frontmatter VitePress) — la rangée de badges y reste ordonnée par thématique (règle 3 inchangée).

Mise à jour 2026-06-22 — réintégration du badge Best Practices (validé)

Le badge OpenSSF Best Practices est remis dans la section « Conformité » du README (famille « Sécurité & supply-chain », projet 13301).

Ce n’est pas un revirement par rapport au 2026-06-19, mais l’effet d’un changement d’état. Le retrait visait un badge affiché à vide : tant que le questionnaire n’était pas rempli ni soumis, le badge n’attestait rien (au mieux « in progress »), c’était décoratif (règle 1). Désormais le projet est soumis et le questionnaire validé par l’OpenSSF : le badge n’apparaît « passing » que parce qu’un tiers (la plateforme bestpractices.dev) a accepté les réponses, chacune adossée à une preuve réelle du dépôt (cf. answer-sheet : ~50 critères Met sourcés, ~12 N/A justifiés, 0 Unmet). C’est donc un état vérifié — pas une auto-déclaration à vide — qui rentre dans le cadre de la règle 1.

Nuance conservée : un badge auto-rempli reste plus faible qu’un score recalculé en continu (Scorecard). D’où la hiérarchie inchangée — Scorecard en tête sous le titre (le plus structurant), Best Practices rangé dans sa famille plus bas. La discipline d’honnêteté tient : on affiche le badge parce qu’il est validé, et on le retirerait s’il retombait « in progress ».

Alternatives écartées

• Tout badge sans condition d’honnêteté (« si un badge existe upstream, on l’affiche »). Écarté : ouvre au badge décoratif, qui ment sur l’état et contredit ADR 0052. Le badge le plus visible serait le plus faux.
• Badges figés recopiés à la main (scores statiques mis à jour manuellement). Écarté : un palier recopié périme silencieusement — exactement le travers « état complété à la main = preuve invalide » (ADR 0046). Un badge de score doit être dynamique ou ne pas exister.
• Rangée non ordonnée (ajouter au fil de l’eau). Écarté : perd le signal « quelles familles » ; rejoue l’arbitrage de placement à chaque ajout.
• Ne pas faire d’ADR (laisser le passage d’audit décider seul). Écarté : la posture d’affichage est structurante et transverse (elle vaut pour tout badge futur, pas seulement ceux de 2026-06-16) — donc tracée par ADR (ADR 0057/0061). Un passage d’audit constate et propose ; il ne décide pas une doctrine durable.