81 lines
4.2 KiB
Markdown
81 lines
4.2 KiB
Markdown
<!-- file: docs/templates/004-FILE_FAMILY_CONTRACTS.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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`](../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 :
|
|
|
|
```text
|
|
file or family
|
|
responsibility
|
|
modification rule
|
|
```
|
|
|
|
Lorsque ces informations sont utiles, le projet MAY ajouter :
|
|
|
|
```text
|
|
source of truth / generated status
|
|
local owner or reference
|
|
validation or synchronization requirement
|
|
```
|
|
|
|
Une table Markdown convient aux registres structurés :
|
|
|
|
```markdown
|
|
| 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 :
|
|
|
|
1. sélectionner uniquement les fichiers ou familles dont le contrat local apporte une information non évidente ;
|
|
2. référencer l'owner détaillé existant au lieu de recopier ses règles ;
|
|
3. regrouper les chemins qui partagent réellement le même contrat plutôt que créer une entrée par fichier ;
|
|
4. distinguer explicitement source de vérité et artefact généré lorsque cette distinction existe ;
|
|
5. 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
|
|
|
|
```markdown
|
|
| 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.
|