Aller au contenu principal

Maintenir ce manuel

La source vit dans le dépôt de l’application afin qu’un changement de comportement et sa documentation puissent arriver ensemble. Les captures générées sont publiées dans un bucket Cloudflare R2, sous un préfixe versionné par version du manuel, et ne sont jamais ajoutées à l’arborescence de l’application.

Modifier le texte​

  1. Modifie ou ajoute le fichier MDX anglais sous docs-site/docs.
  2. Mets à jour le fichier correspondant pour chaque langue publiée sous docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
  3. Ajoute une nouvelle page à docs-site/sidebars.ts.
  4. Mets à jour docs-site/metadata/features.json lorsque la couverture change.
  5. Mets à jour les entrées correspondantes de docs-site/metadata/surface-inventory.json. Une surface devient vérifiée uniquement lorsque son interface de production actuelle, son texte et sa couverture par capture ont tous été examinés.
  6. Exécute make manual_check.
  7. Examine localement la version de production avec make manual_serve, y compris le sélecteur de langue et chaque route localisée.

La validation exige que chaque arborescence de traduction publiée contienne les mêmes chemins de pages que l’arborescence anglaise. Elle rejette aussi les corps de pages traduits identiques à l’anglais, afin que de nouvelles pages ne soient pas publiées discrètement comme copies non traduites. Les URL publiques anglaises restent inchangées ; les autres langues sont publiées sous leur propre préfixe de langue versionné.

Garder l’inventaire de couverture comme référence​

L’inventaire définit le périmètre du manuel anglais V1 : chaque page Beamer, chaque page ou éditeur Settings V2 et chaque flux majeur qui crée ou modifie substantiellement des données ou une configuration transversale. Chaque entrée consigne le fichier source auquel elle appartient et une ancre de texte source. La validation échoue si l’un ou l’autre disparaît : une modification de route ou d’interface doit alors mettre à jour l’audit du manuel au lieu de laisser une ligne obsolète invisible.

Les états de couverture ont volontairement des sens stricts :

  • Planifiée signifie que la surface est connue mais n’a pas encore une couverture complète.
  • Documentée signifie qu’un texte utile existe, mais que les captures de production actuelles ou une revue d’exactitude de bout en bout manquent encore.
  • Vérifiée signifie que la page de fonctionnalité concernée est vérifiée et appuyée par des captures de production enregistrées.

Exécute npm --prefix docs-site run coverage:complete pour le contrôle de publication. Il échoue jusqu’à ce que toute surface inventoriée soit vérifiée ; les versions incrémentales ordinaires du manuel continuent d’indiquer le nombre restant sans bloquer les commits par sujet.

Ajouter un cas de capture​

  1. Ajoute ou réutilise un banc de capture Flutter déterministe.
  2. Enregistre le cas et ses quatre images source dans docs-site/metadata/screenshot-cases.json.
  3. Place le texte de démonstration visible derrière manualScreenshotText(...) pour chaque langue prise en charge lorsqu’il n’est pas déjà fourni par les fichiers de localisation de l’application.
  4. Capture chaque langue dans le répertoire de staging local ignoré par Git (make manual_screenshots) ; la CI publie le résultat dans le bucket R2.
  5. Génère et valide le manifeste média.
  6. Référence le cas avec <ManualScreenshot caseId="…" alt="…" /> dans chaque page de langue.

Chaque capture de l’application dans une page rédigée doit utiliser ManualScreenshot. Les liens directs vers les médias de capture — anciennes images lotti-docs ou le bucket R2 lui-même — échouent à la validation du manuel, car ils ne peuvent pas suivre le choix global Mobile/Ordinateur ni le thème clair/sombre du manuel.

Chaque cas automatisé doit fournir les variantes mobile clair, mobile sombre, ordinateur clair et ordinateur sombre dans chaque langue publiée. Le composant du manuel choisit la langue et le thème correspondants. Changer Mobile/Ordinateur sur une image met immédiatement à jour toutes les captures et persiste entre les pages et les onglets de manuel ouverts.

Publier une version​

La source du manuel n’est pas copiée pour chaque version de l’app. Le tag de version de l’app en conserve déjà l’état exact. Chaque tag de version publie automatiquement le manuel de sa version : si les pages, les tests de captures d’écran ou les données de démonstration du manuel ont changé depuis la version précédente, la CI construit le site et réalise ses captures à partir du tag ; sinon, la nouvelle version reprend l’instantané de la version précédente. Les instantanés de version ne sont jamais écrasés. L’app ouvre le manuel de sa propre version. Les dix instantanés de version les plus récents restent en ligne, et un lien vers toute autre version mène à la version la plus récente. Un manuel de version peut aussi être publié à la main par une exécution du workflow indiquant la version marketing. Le sélecteur de version lit un catalogue en direct écrit à chaque déploiement, si bien que les anciens manuels listent aussi les versions parues après eux.