Rédiger un document de conception ou une RFC sur laquelle les relecteurs peuvent statuer

Objectif

Faire trancher un changement substantiel par les personnes qui devront vivre avec, sur la base d'un document unique qu'elles peuvent lire en vingt minutes, avant que quiconque n'écrive le code. Le document sert ensuite de trace expliquant pourquoi le système se présente comme il se présente.

Prérequis

Un changement trop important ou trop contesté pour tenir dans la description d'une pull request ; un ensemble connu de relecteurs ayant l'autorité d'accepter ; un endroit où le document réside à côté du code (un répertoire docs/rfcs/, un fichier numéroté, une pull request). La PEP 1 (citée) et le modèle de RFC de Rust (cité) sont des exemples publics de tels processus ; les modèles de documents de conception de Google (cités) exigent que les auteurs traitent la sécurité, l'internationalisation, le stockage et la confidentialité, ces parties étant, dans la plupart des cas, relues par des experts du domaine.

Étapes

1. Rédiger l'énoncé du problème avant toute proposition : qui est concerné, ce qui se passe aujourd'hui, quelle contrainte impose un changement. Si le problème ne peut pas être énoncé en un paragraphe, le document n'est pas prêt.
2. Lister les objectifs sous forme d'énoncés numérotés et vérifiables, ainsi que les non-objectifs qui délimitent le périmètre. Les non-objectifs empêchent la relecture de s'étendre à des souhaits connexes.
3. Expliquer la proposition deux fois, comme le fait le modèle de Rust : une explication de niveau guide, sur la façon dont le changement se présente à un utilisateur, puis une explication de niveau référence, avec la sémantique précise, les formats et les cas limites.
4. Consigner les alternatives envisagées et la raison du rejet de chacune. La PEP 1 demande de conserver les idées rejetées avec leur justification, pour que la discussion ne soit pas répétée ; le modèle de Rust comporte une section raisons et alternatives dans le même but.
5. Énoncer honnêtement les inconvénients, les effets sur la compatibilité, la migration et le déploiement, ainsi que le coût opérationnel ; un document sans inconvénient se lit comme un plaidoyer.
6. Terminer par les questions non résolues, réparties entre « doit être tranché lors de cette relecture » et « peut être réglé pendant l'implémentation ».
7. Diffuser le document avec une échéance de relecture, répondre aux commentaires dans le document plutôt que dans un fil de discussion, et consigner l'issue dans une ligne de statut (brouillon, accepté, rejeté, remplacé). Conserver les documents rejetés ; ils répondent à la prochaine personne qui aura la même idée.

Résultat attendu

Les relecteurs débattent du problème et des compromis, pas du contexte manquant ; le document accepté devient la référence pour l'implémentation et, comme le suggère le chapitre de Google cité, une mesure, au lancement, permettant de vérifier si les objectifs énoncés ont été atteints.

Limites et base de vérification

Un document de conception n'est pas une spécification ; les détails changent pendant l'implémentation, et le document devrait indiquer quelles parties sont contraignantes. Pour les petits changements, le formalisme coûte plus qu'il ne fait gagner. La structure suit les modèles cités ; aucun effet sur la qualité des décisions n'est mesuré ici.