Summary
[!note] 📚 Série Pilotflow : Construire un Addon Gmail
- Le Mensonge à 50 000 $ qui a failli tuer mon Addon Gmail — 8 juin
- Les Niveaux de Portée OAuth Gmail décryptés — 15 juin
- Analyse du Codebase avant le Développement ← vous êtes ici
- Documents Légaux pour les Addons Gmail — 29 juin
La décision de périmètre avait été prise. L’analyse OAuth du post 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 d’abord lu.
Le dépôt Pilotflow existait dans un état partiellement construit depuis des travaux antérieurs. 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 semblait plus lente sur le moment, s’est en réalité avérée plus rapide. La revue a mis en évidence trois constats qui auraient été significativement plus coûteux à découvrir après l’implémentation.
La Situation des Branches
La première chose qu’une revue de codebase doit répondre : quel est l’état réel de ce code ? Pas “que dit le README”, mais ce qui existe sur chaque branche, ce qui est complet, ce qui est à moitié construit.
La branche principale avait une seule portée OAuth et un étiquetage d’email basique. La branche de développement — nommée backup-code-20260202, ce qui n’est pas un nom particulièrement rassurant — avait 4 146 lignes supplémentaires : un processeur d’emails avec transfert et actions par lot, un module d’utilitaires serveur, une interface tableau de bord complète, et un framework de tests de bout en bout.
Elle avait également sept portées OAuth, contre une seule sur la branche principale.
Aucune branche n’était “la bonne”. 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 par rapport à l’analyse de portée.
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 gonflement de portée (demander des permissions pour des fonctionnalités pas encore nécessaires). Comprendre les deux branches d’abord a rendu la décision de fusion évidente plutôt qu’un pile ou face.
À retenir : Avant tout développement non trivial, documentez l’état de chaque branche active. L’hypothèse la plus dangereuse dans l’archéologie de codebase est que
mainreflète l’intégralité du projet.
Le Bug de Retraitement
Le deuxième constat était celui qui comptait le plus.
Le mécanisme central de Pilotflow est un moteur de traitement : scanner la boîte de réception, appliquer des règles aux emails correspondants, étiqueter les messages traités pour ne pas les retraiter. L’étiquette était pilotflow-processed. La logique vérifiait la présence de cette étiquette avant de toucher un email.
Cela semblait correct en isolation. Ce 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 email traité par Pilotflow, la réponse arrive comme un nouveau message — sans l’étiquette pilotflow-processed. Le moteur rescanne alors le fil, rencontre la réponse non étiquetée, et traite l’intégralité du fil — y compris le message original qu’il avait déjà traité.
Le résultat était un traitement en double silencieux. Pas un crash. Pas de log d’erreur. Juste le même email traité deux fois, ou trois fois, selon le nombre de réponses reçues. Pour un outil qui archive, étiquette ou transfère des emails, le traitement en double n’est pas un problème de performance — c’est un problème d’exactitude qui affecte les données utilisateur.
Le bug n’était visible qu’en traçant le cycle de vie complet :
Email arrive
→ Traité par Pilotflow
→ Étiqueté "pilotflow-processed"
Réponse arrive dans le même fil
→ Nouveau message, pas d'étiquette "pilotflow-processed"
→ Fil réexaminé par Pilotflow
→ Message original déjà traité re-rencontré
→ Traité À NOUVEAU
La chaîne d’événements qui cause le problème semble tout à fait raisonnable à chaque étape individuelle. C’est ce qui rend cette catégorie de bug difficile à trouver en lisant seul le code des fonctionnalités — il faut tracer le cycle de vie, pas seulement la fonction.
La correction architecturale était claire 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 suivants, indépendamment des nouveaux messages qui arrivent. L’étiquette au niveau du fil remplace l’étiquette au niveau du message comme mécanisme d’idempotence.
[!note] Pourquoi c’est important pour les nouvelles fonctionnalités Les fonctionnalités d’action par lot en cours d’ajout 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 cela pendant la revue — avant d’implémenter les actions par lot — a empêché le bug d’être intégré dans les hypothèses du nouveau code.
Le Framework Notiwise
Le troisième constat était le positif.
Avant Pilotflow, il y avait Notiwise — un addon de calendrier Google Workspace. Construire Notiwise avait nécessité de figurer un chemin de lancement complet : sélection de portée OAuth, création de documents légaux, configuration de l’écran de consentement OAuth, structure de vidéo de démonstration, exigences de soumission au Workspace Marketplace. Douze phases de travail, soigneusement documentées dans le fichier de projet.
Quand j’ai ouvert le dépôt Pilotflow, ce framework était là 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 reconstitution des mêmes questions depuis les premiers principes.
C’est à ça que ressemble les intérêts composés dans le travail de projet. Les deux heures passées à documenter le processus de lancement de Notiwise n’ont pas produit de documentation — elles ont produit un actif réutilisable qui rend chaque addon Google Workspace suivant plus rapide et plus fiable à construire. Pas parce que la documentation est consultée occasionnellement, mais parce qu’elle encode des décisions qui n’ont pas besoin d’être refaites.
À retenir : La documentation de processus d’un projet précédent est un actif productif, pas un artefact de conformité. La valeur se manifeste sur le projet suivant — mais seulement si la documentation était suffisamment spécifique pour être réellement réutilisée, pas juste assez 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 portée 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 concentrée. Elle a évité qu’au moins deux problèmes composés soient intégrés dans les fondations, et elle a éliminé une semaine de travail de planification en réutilisant un framework existant.
L’instinct de lire avant d’écrire semble 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 chaque branche active — 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 de bout en bout avant de les étendre — le bug est 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
- Cherchez les frameworks réutilisables 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é.
→ Suivant : Documents Légaux pour les Addons Gmail en 15 Minutes
