Arc 6 Quête A3a

La Cité-Monde, le Choix du Bâtisseur

Monorepo ou polyrepo, la décision stratégique

Au bout d'une route qui traverse trois royaumes, se dresse la Cité-Monde, une métropole si vaste qu'elle possède ses propres saisons. Des milliers d'artisans y travaillent dans le même atelier interconnecté : forgerons, tisserands, alchimistes, scribes, tous sous le même toit titanesque.

L'Architecte de la Cité t'accueille en haut de la tour centrale. De là, tu peux voir l'immensité de l'atelier en contrebas.

« Avant de descendre dans les arcanes techniques de la Cité, il faut comprendre pourquoi certains royaumes ont choisi ce modèle et d'autres non. C'est une décision stratégique, pas seulement technique. Laisse-moi te montrer les deux voies, et le prix de chacune. »

Monorepo vs Polyrepo

Quand une équipe ou une entreprise gère plusieurs projets, deux approches s'opposent :

Polyrepo - un dépôt par projet

C'est l'approche la plus courante. Chaque projet, service ou bibliothèque a son propre dépôt Git.

# Polyrepo - chaque projet est un dépôt séparé
github.com/mon-equipe/frontend       # Application React
github.com/mon-equipe/backend-api    # API Node.js
github.com/mon-equipe/auth-service   # Service d'authentification
github.com/mon-equipe/shared-utils   # Bibliothèque partagée
github.com/mon-equipe/mobile-app     # Application mobile
github.com/mon-equipe/infra          # Configuration Terraform

Avantages :

  • Chaque projet est indépendant - son propre historique, ses propres branches, sa propre CI
  • Permissions fines : tu peux donner accès à un dépôt sans donner accès aux autres
  • Clones rapides : chaque dépôt est léger
  • Simplicité : pas besoin d'outillage spécial
  • Équipes autonomes : chaque équipe gère son dépôt comme elle veut

Inconvénients :

  • Partage de code difficile : la bibliothèque partagée doit être publiée comme un package, avec sa propre version
  • Refactoring transversal pénible : changer une API impacte plusieurs dépôts = plusieurs PR, plusieurs reviews, plusieurs déploiements
  • Incohérences : chaque dépôt peut utiliser des versions différentes des outils, du linter, du framework
  • Dependency hell : gérer les versions entre dépôts qui dépendent les uns des autres

Monorepo - tout dans un seul dépôt

L'approche monorepo met tout le code de l'organisation dans un seul dépôt Git géant.

# Monorepo - tout est dans un seul dépôt
github.com/mon-equipe/platform/
├── apps/
│   ├── frontend/        # Application React
│   ├── backend-api/     # API Node.js
│   ├── mobile-app/      # Application mobile
│   └── auth-service/    # Service d'authentification
├── packages/
│   ├── shared-utils/    # Bibliothèque partagée
│   ├── ui-components/   # Composants UI partagés
│   └── config/          # Configuration partagée (ESLint, TS, etc.)
├── infra/               # Configuration Terraform
└── docs/                # Documentation centralisée

Avantages :

  • Partage de code trivial : importer un package partagé = un simple import, pas de publication de version
  • Refactoring atomique : changer une API partagée + tous ses consommateurs dans un seul commit
  • Cohérence : une seule version des outils, une seule configuration, un seul standard
  • Visibilité : tout le monde voit tout le code (transparence)
  • Tests d'intégration simples : tout est là, pas besoin de mocker les autres services

Inconvénients :

  • Taille : le dépôt peut devenir énorme (des Go d'historique)
  • Outillage nécessaire : Git seul ne suffit pas, il faut des outils spécialisés
  • CI/CD complexe : construire et tester tout à chaque commit serait trop lent
  • Permissions : tout le monde voit tout (peut être un inconvénient dans certains contextes)
  • Formation : l'équipe doit apprendre de nouveaux outils

Qui utilise quoi ?

Entreprise Approche Détail
Google Monorepo Un seul dépôt pour la quasi-totalité du code (des milliards de lignes). Outil maison : Piper/CitC
Meta (Facebook) Monorepo Un monorepo mercurial massif pour le code principal
Microsoft Mix Windows est dans un monorepo géant (VFS for Git). Autres projets en polyrepo
Twitter/X Monorepo Un monorepo avec Pants comme build tool
Netflix Polyrepo Centaines de microservices, chacun son dépôt
Amazon Polyrepo Philosophie "two-pizza teams" avec services indépendants
Vercel Monorepo Utilise Turborepo (qu'ils ont créé)

Il n'y a pas de "bonne" réponse universelle. Le choix dépend de la taille de l'équipe, de la culture de l'entreprise, et du niveau d'interdépendance entre les projets. Un monorepo sans outillage adapté est pire qu'un polyrepo.

L'Architecte marque une pause. « Maintenant que tu connais les deux approches, parlons du coût. Un monorepo n'est pas gratuit. Il exige des outils, de la discipline, et des compromis que tout le monde n'est pas prêt à accepter. »

Le coût d'un monorepo

Un monorepo n'est pas gratuit. Avant de te lancer, comprends bien ce que cela implique :

Outillage

Tu devras mettre en place et maintenir des outils comme Nx, Turborepo ou Bazel. Ces outils ont leur propre courbe d'apprentissage et leurs propres bugs. Quelqu'un dans l'équipe devra devenir l'expert.

Formation

Tous les développeurs doivent comprendre les nouveaux workflows. "Pourquoi mon build ne lance pas tout ?" "Comment je cible un seul projet ?" "Pourquoi le cache me donne un ancien résultat ?" Prévois du temps de formation.

CI plus complexe

La CI doit être plus intelligente. Au lieu d'un simple "npm test", tu dois implémenter l'affected detection, le cache distribué, et la parallélisation. Les pipelines CI sont plus complexes à écrire et à déboguer.

Git sous pression

Git n'a pas été conçu pour des dépôts de plusieurs Go. Tu devras utiliser le partial clone, le sparse checkout, et potentiellement git maintenance pour garder les performances acceptables.

# Activer la maintenance automatique de Git
# (optimise les pack files, met à jour les index, etc.)
git maintenance start

# Cela lance des tâches en arrière-plan :
# - gc : nettoyage des objets orphelins
# - commit-graph : accélérer les parcours d'historique
# - prefetch : pré-récupérer les objets du remote
# - loose-objects : consolider les objets épars
# - incremental-repack : repack incrémental des pack files

Quand choisir un monorepo ?

  • Tes projets partagent beaucoup de code entre eux
  • Tu fais régulièrement des refactorings transversaux
  • Tu veux imposer des standards uniformes (linter, formatter, conventions)
  • Tu as les ressources pour investir dans l'outillage
  • Ton équipe est prête à apprendre de nouveaux outils

Quand rester en polyrepo ?

  • Tes projets sont très indépendants les uns des autres
  • Tu as des équipes autonomes avec des technologies différentes
  • La simplicité est ta priorité
  • Tu n'as pas les ressources pour investir dans l'outillage monorepo
  • Les permissions d'accès au code doivent être strictement séparées

« Tu vois la Cité-Monde en bas ? Elle est magnifique. Mais elle n'a pas été construite en un jour. Il a fallu des architectes, des routes, des systèmes d'approvisionnement, des règles de cohabitation. Un monorepo sans outillage, c'est une cité sans routes - le chaos total. Si tu choisis cette voie, investis dans les fondations. »

« Tu connais maintenant le choix stratégique et son prix. Si tu décides que la Cité-Monde est la bonne voie pour ton royaume, il te reste à en maîtriser les arcanes techniques : comment Git et ses outils gèrent concrètement un atelier de cette taille. »

Prochaine étape : A3b, Les Arcanes de la Cité.