Un script de conversion qui a ratissé trop large

Le français et l’italien exigent une apostrophe typographique plutôt qu’une apostrophe droite, et il y a un test qui l’impose. Écrire ce caractère directement dans un fichier source n’est pas fiable : selon la façon dont le fichier est produit, un interpréteur de commandes, un heredoc ou un outil d’édition peuvent le remettre à plat. Nous écrivons donc le caractère droit et nous exécutons ensuite un petit script qui le convertit.

Ce script masque le code. Tout ce qui se trouve entre accents graves et tout ce qui se trouve dans un bloc délimité est laissé intact, car une apostrophe à l’intérieur d’un fragment de code changerait le fragment, et la comparaison de faits passerait au rouge à juste titre.

Il a été exécuté avec un motif générique sur tout un dossier de langue. Il a converti une apostrophe à l’intérieur d’une citation de sortie de programme, dans un article écrit par une autre ronde, qui se trouvait par hasard dans le même dossier.

Le masquage était correct et la cible était fausse

La ligne qu’il a abîmée était une citation de ce qu’une commande avait affiché, placée entre guillemets comme du texte courant plutôt que balisée comme du code. Quelque chose de la forme Locking administration user's password. Cette apostrophe appartient à la machine qui l’a émise, et la courber fait dire à l’article que la machine a dit quelque chose qu’elle n’a pas dit.

La règle de masquage est juste. Les accents graves et les blocs délimités sont du code. Une citation de sortie de programme composée comme de la prose n’est pas marquée comme du code et ne peut pas être distinguée de la prose en regardant les caractères, car c’est précisément ce qu’elle est : de la prose qui cite une machine.

Le défaut n’est donc pas dans le masquage. Il est dans la sélection. Trois articles issus d’autres rondes ont été modifiés par un script écrit pour en toucher quatre.

Pourquoi la vérification de construction n’a rien remarqué

C’est la partie qui se généralise au-delà d’un seul script.

Nos articles sont générés. La source est du markdown, la sortie est faite de fichiers générés versionnés, et il y a une vérification qui reconstruit depuis la source et exige que le résultat soit identique octet pour octet à ce qui est versionné. S’ils divergent, elle passe au rouge.

Ils n’ont pas divergé. Le script a changé la source, la construction a été lancée, la sortie a été régénérée depuis la source modifiée, et les deux correspondaient parfaitement. La vérification répond à « la sortie est-elle cohérente avec la source », qui est une vraie question et pas celle-ci. Rien dans la chaîne ne répond à « cette ronde n’a-t-elle changé que ce qu’elle devait changer ».

Le test de typographie non plus, pour la même raison à l’envers : une apostrophe courbe en français est le caractère correct. Le changement a rendu le fichier plus conforme, pas moins.

La seule chose qui l’a montré est git status sur des chemins en dehors des fichiers propres à la ronde. C’est désormais la règle : après avoir exécuté une transformation quelconque, listez les fichiers modifiés et confirmez que chacun d’eux est le vôtre.

La règle qui en découle

Exécutez un script de transformation sur les noms de fichiers de votre propre ronde. Jamais sur un motif générique portant sur un répertoire.

Cela paraît évident une fois écrit, et ce ne l’était pas au moment de l’écrire, car un motif générique sur un dossier de langue est la manière naturelle d’exprimer « convertir les articles français », et le script avait une propriété de sûreté correcte qui le faisait paraître sûr : il exige au moins un remplacement par fichier, afin qu’une exécution qui ne fait rien en silence ne puisse pas annoncer un succès. Cette vérification porte sur le succès vide. Elle ne dit rien sur la portée.

Une vérification de sûreté qui protège contre le fait d’en faire trop peu n’est pas une vérification de sûreté contre le fait d’en faire trop. Ce sont deux propriétés distinctes et elles demandent des mécanismes distincts.

Deux versions plus petites du même problème

La ronde qui a rencontré cela a aussi rencontré deux défauts de traduction qui viennent de la même famille : quelque chose qui aurait dû être à l’abri de toute modification n’était pas marqué comme tel.

Une directive de cache apparaissait dans la source comme de la prose nue plutôt qu’entre accents graves. Deux langues l’ont traduite, ce qui transforme un mot-clé en tournure, et l’une d’elles a en plus mis au pluriel une durée d’un an. Ni l’un ni l’autre n’est attrapé par la comparaison de faits, car cette comparaison couvre ce qui est entre accents graves et ce qui est un chiffre, et un mot-clé nu n’est ni l’un ni l’autre. La réparation consiste à le marquer comme jeton dans les neuf langues, après quoi la comparaison le couvre définitivement.

Le second était un tableau d’intitulés d’interface. L’article anglais s’en servait pour montrer que deux listes de noms s’étaient écartées l’une de l’autre, et il précisait explicitement que l’écart avait été mesuré en anglais. Six des huit traductions ont traduit le tableau. Une paire de noms traduite n’est pas une version plus douce de la mesure ; c’est une autre mesure, qui n’a jamais été prise. Il a fallu 26 remplacements pour défaire cela.

Les deux défauts ont la même forme que l’apostrophe : un morceau de texte qui est une donnée et non de la langue, posé à un endroit où rien ne le marque comme une donnée.

Ce à quoi répond une vérification est plus étroit que ce à quoi elle semble répondre

Les trois mécanismes en jeu ici sont chacun corrects et chacun a répondu à une question voisine de celle qui importait.

Aucune de ces vérifications n’est mal conçue. La défaillance est l’hypothèse selon laquelle un mur de vérifications vertes constitue une couverture, alors que ce qu’il constitue en réalité est la couverture des choses auxquelles quelqu’un a pensé.

La parade la moins coûteuse n’est pas une vérification de plus. C’est de regarder le différentiel, au niveau des noms de fichiers, avant de valider quoi que ce soit qu’un script a produit.

Ce que nous noterions

1. 01Limitez la portée d’une transformation aux fichiers de votre propre ronde. Un motif générique sur un répertoire n’est pas une portée, c’est une catégorie.
2. 02Un garde-fou contre le fait d’en faire trop peu ne dit rien sur le fait d’en faire trop. Ce sont deux propriétés différentes.
3. 03Une citation de sortie de programme est une donnée. Marquez-la comme du code, sinon une transformation de texte la traitera comme de la langue.
4. 04Une vérification de cohérence entre source et sortie est aveugle à un changement présent dans les deux. Elle répond sur l’accord, pas sur l’intention.
5. 05Un changement qui rend un fichier plus correct est le plus difficile à remarquer, car chaque signal de qualité va dans le bon sens.
6. 06Lisez la liste des fichiers de votre propre différentiel. C’est la seule vérification qui réponde à la question de la portée.
7. 07Tout ce qui est un mot-clé a sa place entre accents graves dans la source, dans toutes les langues, sinon quelqu’un le traduira et aucun test ne s’en souciera.
8. 08Une mesure traduite est une mesure inventée. Si l’intérêt d’un tableau est que deux choses diffèrent, le tableau est une preuve et non de la prose.

Pour être clair : les dégâts ont été annulés, la ronde s’est terminée avec la vérification de contenu à 815 fichiers générés sur 815 identiques octet pour octet, la suite web à 4546 verts, les suites des paquets, de la passerelle et des outils à 7236 verts, la comparaison de faits sur 1240 paragraphes sans aucune constatation, les liens à 81 sur 81, les tableaux à 99 sur 99 et le balayage de mise en page à 108 sur 108 à 390 pixels contre une construction de production. Le test de typographie a été prouvé rouge avec deux défauts plantés et vert ensuite. Non prouvé : il y a un seul relecteur par traduction, trois langues n’ont été vérifiées que sur la mise en page, la typographie et le code de réponse HTTP, et les chiffres cités de rondes antérieures n’ont pas été mesurés à nouveau ici.

Issu du travail de plateforme sur Provibr. Ce qu’un second relecteur a trouvé dans les mêmes huit articles est dans Trois défauts qu’aucun script ne pouvait voir, et ce que neuf catalogues font à un ensemble fixe de contrôles est dans Seize mille clés, neuf langues.