Rédiger un document de conception (RFC) permettant aux personnes qui le relisent de se prononcer

Objectif

Faire trancher un changement important par les personnes qui devront vivre avec lui, sur la base d'un document qui se lit en vingt minutes, et avant que quiconque n'écrive le code. Plus tard, ce même document sert de trace expliquant pourquoi le système se présente tel qu'il se présente.

Prérequis

Un changement trop important ou trop controversé pour la description d'une pull request ; des personnes de relecture connues, avec le pouvoir d'approuver ; un emplacement distinct du code (un répertoire docs/rfcs/, un fichier numéroté, une pull request). La PEP 1 et le modèle de RFC de Rust sont des exemples publics de tels processus. Le chapitre consacré à la documentation dans « Software Engineering at Google » indique que les modèles utilisés là-bas exigent de prendre en compte la sécurité, l'internationalisation, les besoins de stockage et la protection des données, et que ces parties sont le plus souvent vérifiées par des personnes spécialistes du domaine concerné.

Étapes

1. Décrire le problème avant toute proposition : qui est concerné, que se passe-t-il aujourd'hui, quelle contrainte impose un changement. Si le problème ne tient pas en un paragraphe, le document n'est pas mûr.
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 déborder vers des souhaits voisins.
3. Expliquer la proposition à deux niveaux, comme le prévoit le modèle de Rust : une fois au niveau de l'utilisation (à quoi ressemble le changement pour les personnes qui l'utilisent), une fois au niveau de la référence, avec la sémantique, les formats et les cas limites précis.
4. Consigner les solutions envisagées et pourquoi chacune a été écartée. La PEP 1 prévoit une section sur les idées rejetées accompagnées de leur justification, afin que la même idée ne soit pas ramenée sur le tapis ; le modèle de Rust réserve à cela la section « Rationale and alternatives ».
5. Nommer honnêtement les inconvénients, les conséquences en matière de compatibilité, la migration et le déploiement, ainsi que les coûts d'exploitation ; un document sans inconvénients se lit comme une publicité.
6. Conclure par les questions ouvertes, réparties entre « doit être tranché dans cette relecture » et « peut être clarifié pendant la mise en œuvre ».
7. Diffuser avec un délai de relecture, répondre aux commentaires dans le document plutôt que dans le chat, et consigner l'issue dans une ligne de statut (brouillon, adopté, rejeté, remplacé). Conserver les documents rejetés : ils répondent à la prochaine personne qui aura la même idée.

Résultat attendu

Les personnes qui relisent débattent du problème et des arbitrages, et non d'un contexte manquant ; le document adopté devient la référence pour la mise en œuvre et — comme le suggère le chapitre cité de Google — au lancement, l'étalon permettant de vérifier si les objectifs fixés ont été atteints.

Limites et base de vérification

Un document de conception n'est pas une spécification ; les détails évoluent pendant la mise en œuvre, et le document devrait préciser quelles parties sont contraignantes. Pour de petits changements, le rituel coûte plus qu'il n'apporte. La structure suit les modèles cités ; l'effet sur la qualité des décisions n'est pas mesuré ici.