ADR en pratique : 3 templates, un projet Symfony, un workflow Git

Cet article est la deuxième partie d'une série sur les ADR. Si vous découvrez le concept, commencez par l'article 1.

Installation en 5 minutes

Pas besoin d'un outil dédié pour commencer. Un répertoire /adr à la racine du projet et une convention de nommage suffisent. Mais si vous voulez automatiser la numérotation et la création de fichiers, adr-tools fait ça proprement.

# Via Homebrew (macOS)
brew install adr-tools

# Via pip (Linux, Python disponible partout)
pip install adr-tools-python

cd mon-projet-symfony
adr init
adr new "Choisir doctrine/migrations plutôt que Flyway"

mon-projet-symfony/
├── adr/
│   ├── 0001-record-architecture-decisions.md
│   ├── 0002-choisir-doctrine-migrations-plutot-que-flyway.md
│   └── README.md
├── src/
└── composer.json

Trois templates, une même décision

Nygard — le minimaliste

# ADR-0003 — Adopter Doctrine Migrations plutôt que Flyway

Date : 2026-03-18
Statut : Accepté

## Contexte

Notre application Symfony 5 utilise Flyway pour les migrations SQL.
Flyway requiert une JVM — incompatible avec notre stack PHP/Docker minimaliste.

## Décision

Adopter doctrine/migrations en remplacement de Flyway.

## Conséquences

- Intégration native Symfony (commande php bin/console doctrine:migrations:migrate)
- Pas de dépendance JVM dans l'image Docker PHP
- Migration des 23 scripts Flyway existants vers le format Doctrine (effort : 2j)
- Rollback intégré via la méthode down()

MADR — le comparatif explicite

# ADR-0003 — Adopter Doctrine Migrations plutôt que Flyway

Date : 2026-03-18
Statut : Accepté

## Contexte et problème

Nous migrons vers Symfony 7. L'équipe utilise Flyway (outil Java) pour les migrations SQL.
Flyway nécessite une JVM — incompatible avec notre stack PHP/Docker minimaliste.

## Options considérées

- **Option A** : Conserver Flyway (outil externe, JVM requise)
- **Option B** : Adopter doctrine/migrations (natif Symfony, PHP)
- **Option C** : Migrations manuelles versionnées (git + SQL)

## Résultat

Option B retenue : doctrine/migrations.

### Avantages

- Intégration native Symfony (`php bin/console doctrine:migrations:migrate`)
- Pas de dépendance JVM dans l'image Docker PHP
- Rollback intégré via `down()` method

### Inconvénients

- Migration des 23 scripts Flyway existants vers le format Doctrine (effort estimé : 2j)

Y-Statement — la phrase structurée

Dans le contexte d'une migration Symfony 5 vers 7 avec contrainte d'image Docker minimale,
face à la dépendance JVM de Flyway,
nous décidons d'adopter doctrine/migrations
afin d'éliminer la dépendance JVM et d'intégrer les migrations au workflow Symfony natif,
en acceptant l'effort de migration des 23 scripts existants (estimé 2 jours).

Tableau comparatif des 3 templates

Recommandation CodexLab : Nygard par défaut. MADR quand vous avez évalué 3 options ou plus. Y-Statement pour les décisions rapides ou les refus.

Cycle de vie d'un ADR

• Proposed — l'ADR est rédigé, la décision n'est pas encore validée
• Accepted — la décision est prise et appliquée
• Deprecated — la décision n'est plus pertinente, mais aucune alternative ne la remplace
• Superseded — un nouvel ADR remplace celui-ci
• Rejected — la proposition a été évaluée et écartée

Règle d'immutabilité : ne jamais modifier un ADR en statut Accepted. Si la décision évolue, créez un nouvel ADR qui supersede l'ancien.

Intégration Git : du commit à la PR review

git commit -m "docs(adr): add ADR-0003 - switch to doctrine/migrations"
git commit -m "docs(adr): accept ADR-0004 - Redis for session storage"
git commit -m "docs(adr): supersede ADR-0001 with ADR-0006"

Exiger un ADR pour toute PR qui modifie composer.json, la structure de la base de données, ou une configuration d'infrastructure.

Gouvernance légère : trois questions à trancher une fois

• Qui peut créer un ADR ? — Tout développeur qui touche au code.
• Qui valide ? — Le tech lead, ou vous-même après relecture à froid (24h).
• Quel critère d'acceptation ? — Contexte honnête, décision actionnée, conséquences négatives documentées.

Le projet exemple complet est disponible sur le repo GitHub CodexLab.

Suite de la série : comment faire appliquer vos décisions par la machine — fitness functions PHP, CI/CD, et détection automatique des dérives.