Summary
[!note] 📚 Série Pilotflow : Construire un Add-on Gmail
- Le Mensonge des 50 000 $ qui a Failli Tuer Mon Add-on Gmail — 6 juillet
- Niveaux des Scopes OAuth Gmail Décodés — 13 juillet
- Analyse de la Codebase Pré-Développement ← vous êtes ici
- Documents Légaux pour Add-ons Gmail — 29 juin
La décision sur les scopes était prise. L’analyse OAuth du billet précédent pointait clairement vers gmail.addons.current.message.readonly — sensible, pas restreint, pas de CASA requis. Il était temps d’écrire du code.
Sauf que je n’ai pas écrit de code. Je l’ai lu en premier.
Le dépôt Pilotflow existait dans un état partiellement construit issu d’un travail antérieur. Mon premier instinct était de reprendre là où le dernier commit s’était arrêté et de commencer à ajouter des fonctionnalités. Mon second instinct, meilleur, était de comprendre ce sur quoi j’allais construire avant d’ajouter quoi que ce soit.
Cette décision, qui paraissait plus lente sur le moment, était en réalité plus rapide. La revue a révélé trois constats qui auraient été significativement plus coûteux à découvrir après l’implémentation.
L’État des Branches
La première chose à laquelle une revue de codebase doit répondre : quel est l’état réel de ce code ? Non pas « que dit le README », mais ce qui existe sur chaque branche, ce qui est complet, ce qui est à moitié construit.
La branche principale contenait un scope OAuth et du labeling basique des e-mails. La branche de développement — nommée backup-code-20260202, ce qui n’inspire pas confiance — comptait 4 146 lignes supplémentaires : un processeur d’e-mails avec transfert et actions batch, un module d’utilitaires serveur, une UI de tableau de bord complète et un framework de tests end-to-end.
Elle avait également sept scopes OAuth, contre un sur la branche principale.
Aucune branche n’était « juste ». La branche principale était la source de vérité pour la production mais en retard sur les fonctionnalités. La branche de développement avait des fonctionnalités absentes de la principale et n’avait jamais été revue à l’aune de l’analyse des scopes.
Fusionner aveuglément aurait introduit l’un de deux problèmes : régression (perdre les fonctionnalités de la branche de développement si elles ne passaient pas la fusion) ou surcharge de scopes (demander des permissions pour des fonctionnalités pas encore nécessaires). Comprendre les deux branches en premier rendait la décision de fusion évidente plutôt qu’un coup de dé.
À retenir : Avant le début de tout développement non-trivial, documentez l’état de chaque branche active. L’hypothèse la plus dangereuse en archéologie de codebase est que
mainreflète l’intégralité du projet.
Le Bug de Retraitement
Le second constat était le plus important.
Le mécanisme central de Pilotflow est un moteur de traitement : scanner la boîte de réception, appliquer des règles aux e-mails correspondants, labeler les messages traités pour ne pas les retraiter. Le label était pilotflow-processed. La logique vérifiait la présence de ce label avant de toucher un e-mail.
Ça paraissait correct en isolation. Ça ne l’était pas.
Le bug : les réponses créent de nouveaux messages dans le même fil. Quand quelqu’un répond à un e-mail traité par Pilotflow, la réponse arrive comme un nouveau message — sans le label pilotflow-processed. Le moteur scanne alors le fil à nouveau, rencontre la réponse sans label, et traite le fil entier — y compris le message original qu’il avait déjà traité.
Le résultat était un double traitement silencieux. Pas un crash. Pas de log d’erreur. Juste le même e-mail traité deux fois, ou trois fois, selon le nombre de réponses reçues. Pour un outil qui archive, labele ou transfère des e-mails, le double traitement n’est pas un problème de performance — c’est un problème de correction qui affecte les données utilisateur.
Le bug n’était visible qu’en traçant le cycle de vie complet :
E-mail arrive
→ Traité par Pilotflow
→ Labelé "pilotflow-processed"
Réponse arrive dans le même fil
→ Nouveau message, sans label "pilotflow-processed"
→ Fil réexaminé par Pilotflow
→ Message original traité à nouveau rencontré
→ Traité UNE SECONDE FOIS
La chaîne d’événements qui cause le problème paraît totalement raisonnable à chaque étape individuelle. C’est ce qui rend cette catégorie de bug difficile à trouver en lisant uniquement le code de fonctionnalité — il faut tracer le cycle de vie, pas seulement la fonction.
Le correctif architectural était clair une fois le bug identifié : suivre les IDs de fils traités, pas les IDs de messages. Une fois qu’un fil a été traité, le sauter entièrement lors des scans ultérieurs, quel que soit le nombre de nouveaux messages arrivés. Le label au niveau du fil remplace le label au niveau du message comme mécanisme d’idempotence.
[!note] Pourquoi ça compte pour les nouvelles fonctionnalités Les fonctionnalités d’action batch ajoutées dans la branche de développement auraient hérité de ce bug. Une action censée s’exécuter une fois par fil se serait exécutée une fois par réponse. Trouver ça pendant la revue — avant d’implémenter les actions batch — a empêché le bug d’être ancré dans les hypothèses du nouveau code.
Le Framework Notiwise
Le troisième constat était le positif.
Avant Pilotflow, il y avait Notiwise — un add-on de calendrier Google Workspace. Construire Notiwise avait nécessité de concevoir un chemin de lancement complet : sélection des scopes OAuth, création de documents légaux, configuration de l’écran de consentement OAuth, structure de la vidéo de démonstration, exigences de soumission au Workspace Marketplace. Douze phases de travail, soigneusement documentées dans le fichier projet.
En ouvrant le dépôt Pilotflow, ce framework se trouvait dans le vault, prêt à être réutilisé.
Le chemin de lancement de Pilotflow était structurellement identique à celui de Notiwise. Même plateforme. Même environnement réglementaire. Même séquence de décisions. Réutiliser le framework Notiwise pour la planification de Pilotflow a économisé environ 8 à 12 heures de re-résolution des mêmes questions depuis zéro.
C’est ce à quoi ressemble l’intérêt composé dans le travail de projet. Les deux heures passées à documenter le processus de lancement de Notiwise n’ont pas produit de la documentation — elles ont produit un actif réutilisable qui rend chaque add-on Google Workspace suivant plus rapide et plus fiable à construire. Non pas parce que la documentation est consultée occasionnellement, mais parce qu’elle encode des décisions qui n’ont pas besoin d’être reprises.
À retenir : La documentation de processus d’un projet précédent est un actif productif, pas un artefact de conformité. La valeur apparaît sur le prochain projet — mais seulement si la documentation était suffisamment spécifique pour être réellement réutilisée, pas seulement suffisamment générale pour sembler complète.
Ce que la Revue a Changé
Avant la revue, le plan était : ouvrir la branche de développement, reprendre là où elle s’était arrêtée, commencer à ajouter des fonctionnalités.
Après la revue, le plan était différent :
- Fusionner la branche de développement — les fonctionnalités valaient la peine d’être incluses, les ajouts de scopes justifiés par l’inventaire des fonctionnalités
- Corriger d’abord le bug de retraitement — avant de toucher tout nouveau code, établir une idempotence correcte au niveau du fil
- Utiliser le framework Notiwise — appliquer directement la checklist de lancement en 12 phases à la planification du lancement de Pilotflow
La revue a coûté une journée de concentration. Elle a évité qu’au moins deux problèmes cumulatifs soient intégrés aux fondations, et elle a éliminé une semaine de travail de planification en réutilisant un framework existant.
L’instinct de lire avant d’écrire paraît improductif quand on est impatient de construire. C’est l’un des investissements de productivité les plus fiables dans le travail logiciel.
Une Checklist pour les Revues Pré-Développement
Si vous construisez sur du code existant :
- Lisez toutes les branches actives — ne supposez pas que main est complète
- Inventoriez les fonctionnalités existantes : ce qui est complet vs partiel vs commencé-et-abandonné
- Tracez les workflows principaux de bout en bout avant de les étendre — le bug se trouve généralement dans le cycle de vie, pas dans la fonction
- Cherchez ce que le code existant suppose, pas seulement ce qu’il fait
- Recherchez des frameworks réutilisables issus de projets passés structurellement similaires
La prochaine étape après la revue : rendre Pilotflow légalement publiable. Google exige une Politique de Confidentialité et des Conditions d’Utilisation avant que l’écran de consentement OAuth puisse être configuré.
→ Suite : Documents Légaux pour Add-ons Gmail en 15 Minutes
— Kékéli
