3.8 KiB
Pattern — contrats locaux de fichiers ou familles
Objectif
Ce pattern aide un projet à expliciter quelques responsabilités de fichiers ou familles durables lorsqu'elles deviennent difficiles à déduire de l'arborescence, de la toolchain ou des règles déjà existantes.
Il complète le contrat documentaire de ../rules/300-DOCUMENTATION.md. Il n'impose aucun fichier particulier au projet destinataire.
Quand l'utiliser
Créer un registre local seulement lorsqu'il réduit une ambiguïté réelle, par exemple lorsque :
- plusieurs familles voisines ont des rôles différents qui provoquent régulièrement des erreurs de placement ;
- un fichier est une source de vérité tandis qu'un autre est généré ou dérivé ;
- une famille possède une règle de modification ou de synchronisation non évidente ;
- des contributeurs doivent savoir quel owner modifier sans relire plusieurs documents spécialisés.
Ne pas l'utiliser pour inventorier chaque fichier d'un petit dépôt, recopier les rôles standards déjà décrits par PGR ou dupliquer un manifeste/build system qui possède déjà l'information.
Forme minimale
Le nom et l'emplacement appartiennent au projet destinataire. docs/rules/FILE_CONTRACTS.md est un nom possible, pas une convention PGR obligatoire.
Une entrée utile contient au minimum :
file or family
responsibility
modification rule
Lorsque ces informations sont utiles, le projet MAY ajouter :
source of truth / generated status
local owner or reference
validation or synchronization requirement
Une table Markdown convient aux registres structurés :
| Fichier ou famille | Responsabilité | Règle de modification |
|--------------------|----------------|------------------------|
| `<path-or-pattern>` | `<rôle durable>` | `<quand/comment modifier>` |
Une liste courte est préférable lorsqu'elle reste plus lisible. La forme n'est pas normative ; la clarté de la responsabilité l'est pour le projet qui choisit d'adopter ce contrat.
Règles d'adaptation
Lors de l'instanciation :
- sélectionner uniquement les fichiers ou familles dont le contrat local apporte une information non évidente ;
- référencer l'owner détaillé existant au lieu de recopier ses règles ;
- regrouper les chemins qui partagent réellement le même contrat plutôt que créer une entrée par fichier ;
- distinguer explicitement source de vérité et artefact généré lorsque cette distinction existe ;
- supprimer ou fusionner une entrée devenue redondante lorsque son rôle est désormais évident ailleurs.
Le registre SHOULD évoluer lorsqu'une responsabilité ou règle de modification change réellement. Il SHOULD NOT être modifié uniquement parce qu'un nouveau fichier respecte déjà une famille décrite.
Exemple abstrait
| Fichier ou famille | Responsabilité | Règle de modification |
|--------------------|----------------|------------------------|
| `config/*.example` | Décrire les exemples versionnés de configuration locale. | Mettre à jour lorsqu'une option utilisateur versionnée est ajoutée ou retirée ; ne jamais y placer de secret réel. |
| `generated/**` | Contenir les sorties reconstruisibles produites par la toolchain choisie. | Ne pas modifier manuellement ; régénérer depuis la source de vérité documentée. |
Cet exemple illustre la forme uniquement. Il ne crée aucune règle universelle sur les chemins config/ ou generated/.
Critère de sortie
Le pattern est utile si un nouveau contributeur peut déterminer plus vite où une responsabilité vit et quand modifier une famille sans devoir maintenir un catalogue parallèle du dépôt.
S'il ajoute davantage de cérémonie que d'information, ne pas l'instancier ou le retirer.