Méthodologie de migration¶

Status: CURRENT / GOVERNANCE

Cette page décrit la méthode à suivre lorsqu’une responsabilité historique doit être déplacée, réécrite, isolée ou supprimée.

Elle ne définit pas un calendrier et n’impose pas un mécanisme d’activation unique à tous les composants. Le comportement CURRENT doit toujours être vérifié dans le dépôt et le Runtime concernés.

Principe fondamental¶

On ne migre jamais un composant uniquement parce qu’il existe.

On migre une responsabilité encore utile, vers la couche qui doit réellement la posséder, en conservant les contrats nécessaires et en supprimant les compatibilités seulement lorsqu’elles ne sont plus utilisées.

Les étapes¶

La méthode recommandée est :

1. Observer
2. Comprendre
3. Classer
4. Caractériser
5. Concevoir la cible
6. Migrer ou réécrire
7. Valider
8. Activer selon le mécanisme réel
9. Retirer le legacy devenu inutilisé

Ces étapes peuvent être regroupées pour une petite évolution, mais aucune modification risquée ne doit sauter l’observation et la validation.

1. Observer¶

Avant toute modification, établir le comportement CURRENT.

Questions minimales :

où le composant est-il chargé ?
qui l’appelle ?
quelles données lit-il ?
quelles données écrit-il ?
quel contexte l’exécute : HTTP, CLI, worker, admin, cron, frontend ?
quels tests ou audits couvrent son comportement ?
existe-t-il des appels directs ou des wrappers de compatibilité ?

L’existence d’un fichier ou d’une classe n’est pas une preuve suffisante d’usage Runtime.

2. Comprendre¶

Séparer :

logique métier ;
orchestration ;
transport ;
persistance ;
compatibilité historique ;
patch marchand ;
optimisation ;
diagnostic.

Un composant peut contenir plusieurs de ces responsabilités et devoir être découpé plutôt que migré en bloc.

3. Classer¶

Pour chaque responsabilité, choisir une classe de décision explicite :

conserver CURRENT : correctement placée et encore nécessaire ;
migrer : utile mais portée par la mauvaise couche ;
réécrire : comportement utile, implémentation trop couplée ;
compatibilité temporaire : wrapper nécessaire pendant une transition ;
historique : utile seulement comme trace ou preuve ;
supprimer : aucun consommateur ni contrat utile restant.

La classification doit être justifiée par des preuves, pas par l’âge du code.

4. Caractériser le comportement¶

Avant un refactoring important, protéger ce qui doit rester stable.

Selon le composant :

tests unitaires ;
tests de caractérisation ;
tests d’architecture ;
audits read-only ;
snapshots de sortie ;
métriques avant/après ;
comparaison de projections ;
vérification des statuts resolved, unknown, ambiguous, conflict.

Le but est de savoir précisément ce qui peut changer et ce qui ne doit pas changer.

5. Concevoir la cible¶

La responsabilité doit rejoindre la bonne frontière :

Domain Core : logique métier générique ;
Vertical Module : connaissance propre à une famille produit ;
Read Service : lecture sans mutation persistante ;
Write Service : mutation explicite ;
Runtime : orchestration ;
Adapter : WordPress, SQL, CLI, HTTP, filesystem ;
Projection : vue dérivée et reconstruisible ;
Frontend : consommation de données de lecture.

Le design cible ne doit pas créer une dépendance inverse vers le Runtime, WordPress ou une autre verticale.

6. Migrer ou réécrire¶

Migration¶

Conserver l’algorithme lorsque sa responsabilité est claire et son contrat correct, mais déplacer son intégration vers la bonne frontière.

Réécriture¶

Réécrire lorsque l’ancienne implémentation mélange trop de responsabilités, dépend d’un ancien bootstrap ou encode des contraintes qui ne sont plus valides.

Une réécriture doit être comparée au contrat observable, pas au nombre de lignes ou à la structure de l’ancien fichier.

7. Valider¶

La validation dépend du risque mais peut inclure :

composer test ;
make lint ;
make check ;
make guard-static ;
make guard-runtime ;
make doctor ;
make docs-check ;
tests ciblés ;
audits read-only ;
comparaison des sorties ;
validation des performances et volumes.

Ne jamais annoncer qu’un composant est migré uniquement parce que son nouveau code compile.

8. Activer selon le mécanisme réel¶

Il n’existe pas de progression universelle draft → readonly → active pour tous les composants.

L’activation doit suivre l’autorité CURRENT du domaine concerné.

Exemples :

feed : CCX_ACTIVE_FEEDS + ccx_feed_runtime_active_feeds() ;
verticale : vérifier son bootstrap et son registre Runtime ;
projection : vérifier le Builder, le writer et le Reader réellement consommés ;
frontend : vérifier le bootstrap WordPress, les routes et les templates actifs ;
CLI : vérifier la commande enregistrée via wp help ou le dump de commandes.

Un statut documentaire ne remplace jamais cette vérification.

9. Retirer le legacy¶

Retirer seulement lorsque :

aucun consommateur actif ne le charge ;
aucun test ou outil ne dépend de son chargement direct ;
le comportement utile existe ailleurs ;
les compatibilités ne sont plus nécessaires ;
les vérifications pertinentes sont vertes ;
le retour arrière est compris.

Données : observation avant mutation¶

Pour toute migration qui touche les données ou projections :

Observation
→ Audit read-only
→ Simulation
→ Validation
→ Write Service explicite
→ Vérification

Un dry-run peut encore avoir des effets techniques temporaires. Vérifier l’implémentation au lieu de se fier au nom de la commande.

Patchs historiques¶

Un patch historique peut :

rester nécessaire ;
devenir une règle métier générique ;
rester spécifique à une verticale ;
devenir inutile ;
être remplacé par un contrat plus propre.

Ne jamais recopier automatiquement un patch dans une nouvelle couche.

Règles de sécurité¶

Pas de copier-coller massif de dossiers.
Pas de suppression avant audit des consommateurs.
Pas de logique métier ajoutée au Runtime pour accélérer une migration.
Pas de SQL direct ajouté au Frontend ou à un Read Service.
Pas de mutation cachée dans un audit.
Pas de conversion silencieuse de unknown, ambiguous ou conflict en resolved.
Pas d’activation d’un feed PREPARED par simple modification du registre.
Pas de reclassification d’une page TARGET en CURRENT sans preuve Runtime.

Critère de réussite¶

Une migration est réussie lorsque le système devient plus simple à expliquer et plus difficile à utiliser de travers : responsabilité unique, dépendances explicites, observation reproductible, mutation gouvernée et compatibilités identifiées.