Lire le code et proposer une modification

Une petite modification est une bonne occasion de mettre cette lecture en pratique. Commençons par un comportement que nous pouvons observer.

Conventions de notation

Les noms de fonctions, types, commandes, options et fichiers sont composés en chasse fixe, par exemple describe, wf test ou main.cpp. L’italique introduit un terme lors de sa définition. Les blocs de code donnent les extraits à saisir ; le texte qui les précède précise leur emplacement et leurs prérequis.

Commencer par un problème précis

Une contribution commence souvent par quelque chose de modeste : un appel qui échoue de façon inattendue, un diagnostic peu clair ou un cas que les tests ne couvrent pas encore. Décrivons ce que nous avons fait et le résultat que nous attendions. Cela nous donnera un point de départ plus sûr qu’une réorganisation générale des fichiers.

Nous pouvons ensuite chercher le guide et la décision d’architecture concernés, puis les tests voisins. Les consignes du dépôt proposent de commencer par les ADR 001, 002 et 012 avant celles du domaine modifié.

Il arrive que le comportement voulu exige de changer une décision acceptée. Ce n’est pas une raison de dissimuler le changement : il faut expliquer le problème, proposer l’évolution et préciser les conséquences pour le code existant. Une idée encore proposée reste à distinguer de ce que le programme fait déjà.

Faire apparaître le défaut

Si un tableau de mauvaise taille est accepté par le décodeur, nous pouvons le montrer sans ouvrir de fenêtre. Un petit test Catch2 donnera exactement ces octets au code concerné. Il nous dira ensuite si la correction traite bien ce cas.

Pour une course de terminaison, nous chercherons plutôt à imposer les ordres intéressants avec des doubles déterministes. Pour un problème d’intégration CMake, un petit projet consommateur peut révéler ce que les tests internes ne voient pas.

Enfin, un changement du pont demande une vérification dans un vrai navigateur. Le test précis nous aide à comprendre le défaut ; le parcours complet vérifie que les deux extrémités continuent à travailler ensemble.

Élargir la vérification

Lorsque le test précis passe, nous n’avons pas encore terminé la vérification. Une modification peut corriger un cas et en déranger un autre. Construisons donc dans un répertoire séparé, avec CEF désactivé et WEBFRONT_ENABLE_TESTING=ON, puis lançons CTest.

Le label fast rend les vérifications intermédiaires commodes. Avant de terminer, les consignes demandent la suite complète. Les changements du pont, du cycle de vie des moteurs, des modules ou des ressources Jasmine demandent aussi les tests de navigateur indiqués dans AGENTS.md.

Sur Linux, le parcours CEF utilise Xvfb ; la construction comprend webtest, developer_integration et webfront-wf. Les dépendances sont préparées à la configuration, de sorte que les tests n’aient pas à les chercher sur le réseau public pendant leur exécution.

Laisser une modification que l’on peut comprendre

Relisons maintenant le diff comme si nous n’avions pas participé au travail. Le problème est-il encore reconnaissable ? Le test montre-t-il pourquoi la modification est nécessaire ? Pouvons-nous expliquer qui possède les données et ce qui arrive en cas d’erreur ?

Les documents font partie de cette relecture. Une commande modifiée doit être corrigée dans son guide ; une limite levée ou ajoutée doit être décrite. Le changelog conserve les livraisons, l’état du projet décrit les chemins actuels et les ADR gardent les raisons des décisions.

Le développeur suivant n’aura pas notre conversation ni le souvenir de nos essais. Les sources, le test et l’explication doivent lui permettre de retrouver le raisonnement et de refaire la vérification.

Vérifier sa compréhension

Qu’apporte un test qui montre d’abord le défaut ?

Aller à la documentation source ↗