Idée principale

L'état courant d'un dépôt dit ce que le produit fait aujourd'hui, et rien d'autre. Un Product Manager qui y lit qu'une limite d'export est fixée à cinquante lignes obtient le comportement, pas son motif : le code ne garde aucune trace du fait que deux cents ont été essayées, puis abandonnées pour une raison de temps de réponse.

Cette trace existe pourtant, un cran en dessous. Les commits, les pull requests et les merge requests forment une couche temporelle du même dépôt : ils disent comment on est arrivé à l'état courant. Une discussion de revue de code contient l'objection d'un développeur, la contrainte technique qui a forcé un écart par rapport à la demande initiale, le compromis accepté, la correction faite trois jours après la livraison parce qu'un cas limite était apparu.

La distinction utile n'est donc pas entre le code et les documents, mais entre deux lectures du même dépôt. L'état répond aux questions de comportement — quelle règle s'applique, où est la limite. L'historique répond aux questions de motif — pourquoi cette valeur, pourquoi ce refus, pourquoi ce comportement a changé entre mars et juin. Ce sont deux sources distinctes qui se consultent différemment, et confondre les deux fait chercher dans l'état ce qui n'y a jamais été.

Pourquoi c'est important

Cela récupère une part de ce qu'on croyait perdu en désignant le code comme source de vérité. L'objection habituelle — « le code dit quoi, jamais pourquoi » — vaut pour son état, pas pour son histoire ; une partie du raisonnement produit a été écrite, simplement pas là où on la cherche.

Cela change aussi ce qu'on attend d'une revue de code. Les commentaires d'une merge request cessent d'être une conversation jetable entre deux développeurs : ils sont le seul endroit où l'arbitrage réel a été consigné au moment où il se prenait, sans passer par un document rédigé après coup.

Nuances et limites

L'historique n'est bavard que si quelqu'un l'a fait parler. Un dépôt dont les messages de commit disent « fix » et dont les merge requests sont fusionnées sans un commentaire ne porte aucune intention : la couche existe et elle est vide.

La localisation trompe également. Les discussions les plus riches vivent dans la forge — GitHub, GitLab — et non dans le dépôt cloné ; une réécriture d'historique par écrasement des commits emporte au passage ce qui y avait été inscrit.

Enfin, une intention retrouvée est datée. La raison d'un choix fait il y a trois ans explique ce choix-là ; elle ne justifie pas la règle actuelle, qui a pu être réécrite depuis pour un tout autre motif, sans que rien ne relie les deux moments.

Questions ouvertes

• À quoi reconnaît-on qu'une discussion de merge request mérite d'être promue en décision produit écrite, plutôt que laissée là où elle est consignée ?