113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
<!-- file: docs/templates/007-EXISTING_PROJECT_ADOPTION.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# Pattern — adoption PGR d’un projet existant
|
||
|
||
## Usage
|
||
|
||
Ce pattern aide à préparer une adoption PGR sur un dépôt existant conformément à [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md). Il n’est pas un manifest obligatoire, un générateur de migration ni un remplacement du plan de release local.
|
||
|
||
Il peut être instancié comme étude, plan, tableau de décision ou section d’un document existant si le projet a besoin d’une trace durable. Un petit alignement dont les décisions sont évidentes MAY rester directement documenté dans le delta et le history correspondants.
|
||
|
||
## Baseline autoritaire
|
||
|
||
Consigner uniquement ce qui est réellement établi :
|
||
|
||
```text
|
||
repository / archive : <source locale autoritaire>
|
||
commit / tag : <si connu>
|
||
version : <si applicable>
|
||
snapshot PGR choisi : <version / tag / commit / archive de comparaison>
|
||
validation connue : <preuves déjà acquises et encore pertinentes>
|
||
```
|
||
|
||
Ne pas reconstruire une baseline à partir d’hypothèses ou d’une version plus récente de PGR. Le snapshot PGR est une entrée de comparaison explicitement choisie pour cette opération ; il n'est pas un upstream que le projet doit suivre ensuite.
|
||
|
||
## Inventaire utile
|
||
|
||
Identifier les éléments qui déterminent l’applicabilité :
|
||
|
||
- gouvernance et workflow déjà présents ;
|
||
- langages et build systems réellement utilisés ;
|
||
- plateformes et frameworks présents ;
|
||
- validations et scripts existants ;
|
||
- contraintes locales ou historiques à préserver ;
|
||
- profils PGR sans rapport avec le dépôt, explicitement hors scope si leur confusion est probable.
|
||
|
||
## Mapping d’adoption
|
||
|
||
La classification canonique est `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. La forme exacte du mapping reste libre. Une table courte peut suffire :
|
||
|
||
```text
|
||
Owner / contrat État local Décision Action / justification
|
||
-------------------- ---------------- ------------ -----------------------
|
||
<RULE/PGR owner> <état observé> ADOPT <migration ciblée>
|
||
<contrat local> <état observé> KEEP-LOCAL <raison>
|
||
<RULE/PGR owner> <état observé> OVERRIDE <scope + raison>
|
||
<RULE/PGR owner> <état observé> DEFER <prérequis / déclencheur>
|
||
```
|
||
|
||
Les quatre décisions ont le sens normatif défini par `230-ADOPTION.md`. Ne pas créer une cinquième catégorie uniquement pour éviter de décider si un point est adopté, local, overridé ou différé.
|
||
|
||
## Découpage de migration
|
||
|
||
Pour chaque tranche réellement nécessaire, préciser :
|
||
|
||
```text
|
||
scope : <owners / fichiers / contrats concernés>
|
||
hors scope : <domaines laissés intacts>
|
||
risque principal : <ce qui pourrait être cassé>
|
||
preuve : <gate proportionnée>
|
||
```
|
||
|
||
Le découpage SHOULD favoriser des changements vérifiables indépendamment. Une migration ne doit pas embarquer une technologie future uniquement parce qu’un profil PGR existe.
|
||
|
||
## Historique et compatibilité
|
||
|
||
Noter les conventions qui commencent au point d’adoption et les snapshots historiques qui doivent rester inchangés.
|
||
|
||
Exemples :
|
||
|
||
```text
|
||
- ancienne nomenclature de tags conservée avant <point d’adoption> ;
|
||
- anciennes règles locales conservées dans les histories ;
|
||
- nouvelle convention appliquée uniquement aux prochaines tranches ;
|
||
- dette héritée documentée mais non réécrite rétroactivement.
|
||
```
|
||
|
||
|
||
## Autorité après adoption
|
||
|
||
À la clôture du scope, consigner explicitement que la baseline locale obtenue devient l'autorité des sessions et releases suivantes. Une forme courte suffit :
|
||
|
||
```text
|
||
baseline locale autoritaire : <version / commit / état accepté>
|
||
réalignement PGR automatique : non
|
||
```
|
||
|
||
Les reprises ultérieures partent des règles, plans, architecture et histories du projet. Elles ne recherchent pas automatiquement « la dernière version de PGR ».
|
||
|
||
Si un réalignement futur est souhaité, ouvrir une nouvelle opération bornée : choisir un snapshot PGR précis, comparer ses owners applicables à la baseline locale, classifier les écarts `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`, puis valider seulement le scope retenu. Les snapshots historiques locaux restent inchangés.
|
||
|
||
## Validation de sortie
|
||
|
||
L’adoption du scope est prête lorsque :
|
||
|
||
- chaque owner candidat du scope est classifié ;
|
||
- les changements `ADOPT` sont réellement appliqués ;
|
||
- les `KEEP-LOCAL` et `OVERRIDE` sont compréhensibles et possédés localement ;
|
||
- les `DEFER` ont un motif et restent hors du résultat présenté comme terminé ;
|
||
- les validations nécessaires ont réussi ;
|
||
- le projet reste autonome par rapport au dépôt PGR.
|
||
|
||
## Limites
|
||
|
||
Ce pattern ne décide pas à la place du projet :
|
||
|
||
- quels profils sont applicables ;
|
||
- si Games, KSP ou un autre dépôt doit migrer maintenant ;
|
||
- si une règle locale doit devenir une règle PGR générale ;
|
||
- si une migration doit occuper une ou plusieurs releases.
|
||
|
||
Ces décisions appartiennent au contexte réel du projet et à son plan actif.
|