ADR-055 : Classification des opt-ins par destination¶

Statut¶

Proposé, Forge 1.0.0-rc (ticket ADR-OPTIN-CATEGORIES-001).
Décision de gouvernance et de présentation des opt-ins ; relève du mainteneur.

Date¶

2026-06-29

Contexte¶

Le nombre d'opt-ins officiels s'étend (une vingtaine de paquets forge-mvc-*).
La liste à plat devient difficile à parcourir, que ce soit sur PyPI, dans la commande opt-in:list ou dans la documentation.

Le catalogue canonique existe déjà : cli/optins/catalog.py, OFFICIAL_OPTINS: dict[str, OptIn], source de vérité unique de la famille opt-in:* (ADR-016).
Chaque OptIn porte name, package_dist, package_import, kind et summary.

Le champ kind (route / library / crosscutting) décrit comment la brique se branche : c'est une classification technique.
Il ne dit rien de à quoi sert la brique : il manque un axe fonctionnel, la « destination ».

Deux fausses pistes ont été écartées pour atteindre ce regroupement.

Renommer les paquets par domaine (par exemple forge-mvc-db-mariadb) heurte deux règles.
Le nom d'un paquet PyPI est de l'API publique : renommer un paquet déjà publié serait une rupture (charte, règle C).
Et l'API publique est en anglais (ADR-003), ce qui exclut un préfixe comme bdd.

Réutiliser le champ kind mélangerait deux axes distincts (technique et fonctionnel) et appauvrirait les deux.

Le catalogue est par ailleurs incomplet : il décrit moins d'entrées qu'il n'existe de paquets, plusieurs opt-ins récents n'y figurent pas.

Décision¶

Un axe « destination » ajouté au catalogue, sans renommage¶

On ajoute un champ category à OptIn, distinct de kind.
category exprime la destination fonctionnelle ; kind reste la forme d'intégration technique.
Aucun paquet n'est renommé : les noms de distribution PyPI restent le contrat public, en anglais (ADR-003).

L'identifiant de catégorie est un slug anglais (cohérent avec ADR-003) ; son libellé d'affichage est en français, côté CLI et documentation.

Liste canonique des catégories¶

Slug	Libellé d'affichage	Opt-ins
`database`	Bases de données	`mariadb`, `sqlite`, `postgres`, `mssql`
`media`	Médias et fichiers	`files`, `images`, `video`, `audio`
`security`	Sécurité et accès	`mfa`, `rbac`, `audit`
`communication`	Communication	`mail`, `notifications`, `iot`
`data`	Données et modélisation	`pivot`, `stats`, `workflow`, `import-export`
`i18n`	Internationalisation	`i18n`
`content`	Contenu	`qrcode`
`configuration`	Configuration	`settings`
`operations`	Exploitation et outillage	`deploy`, `admin`, `testing`, `jobs`

Cette liste est la taxonomie unique : la même alimente opt-in:list (sortie groupée) et la navigation du site (sections par destination).
Une seule taxonomie, deux surfaces.

Règle pour tout nouvel opt-in¶

Tout nouvel opt-in officiel déclare sa catégorie dans le catalogue, parmi la liste canonique ci-dessus.
L'ajout d'une catégorie hors liste passe par une mise à jour de cet ADR.

Cas des backends de base de données¶

Les backends BDD (mariadb, sqlite, postgres, mssql) suivent un modèle exclusif (ADR-054) : on en installe un seul par projet, découvert par l'entry point forge_mvc.db_backend.
Ils ne s'« enable » pas comme les autres opt-ins et ne figurent pas dans OFFICIAL_OPTINS.
Ils sont présentés dans une section dédiée « Bases de données » (lecture seule, sémantique « choisis-en un »), distincte des opt-ins composables, et restent pilotés par la famille db:*.

Périmètre¶

Cet ADR fige la taxonomie et la règle de déclaration.
La mise en œuvre (champ category, complétion des entrées manquantes du catalogue, opt-in:list groupé, réorganisation de la navigation du site) relève de tickets distincts.

Conséquences¶

Le catalogue gagne un axe fonctionnel et sera complété pour couvrir tous les paquets existants.
opt-in:list regroupe les briques par destination, plus lisible à mesure que la liste grandit.
La navigation du site reprend la même taxonomie, sans dépendre des noms de paquets.
Aucun nom de paquet n'est touché : pas de rupture de contrat public, pas de churn d'imports.
Un garde-fou de test pourra vérifier que chaque opt-in du catalogue déclare une catégorie de la liste canonique.

Alternatives écartées¶

Renommer les paquets par domaine (forge-mvc-db-*, forge-mvc-media-*...).
Rupture du contrat public pour les paquets déjà publiés (charte, règle C), préfixe français exclu par l'ADR-003, et churn massif (noms PyPI, namespaces importables, imports de tests, entry points, classifiers, documentation) pour un gain surtout cosmétique.

Réutiliser le champ kind.
Mélange un axe technique (intégration) et un axe fonctionnel (destination), au détriment de la clarté des deux.

Ne rien faire.
La liste à plat continue de se dégrader à mesure que le nombre d'opt-ins augmente.

Charte appliquée¶

Principe 8 (noyau minimal, briques opt-in raisonnées) : la classification rend l'offre d'opt-ins lisible sans l'alourdir.
Principe 11 (une seule façon officielle) : une taxonomie unique alimente le CLI et la documentation.
Principe 3 (refus de la magie cachée) : la catégorie est déclarée explicitement dans le catalogue, pas inférée.
Règle C (pas de rupture d'API publique hors release majeure) : on classe sans renommer les paquets.
ADR-003 (API publique en anglais) : slugs de catégorie en anglais.

Référence¶

ADR-016 : unification du modèle opt-in (cycle, verbes).
ADR-052 : stratégie et critères d'admission des opt-ins.
ADR-054 : backends BDD exclusifs, découverts par entry points.
ADR-038 : doc des opt-ins embarquée par paquet, agrégée au site.
cli/optins/catalog.py : catalogue canonique OFFICIAL_OPTINS.