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 vivent dans le dépôt voisin lotti-docs 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 ../lotti-docs, jamais dans ce dépôt.
  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 d’anciennes images lotti-docs é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’application. Le tag de version conserve déjà sa source exacte. L’intégration continue récupère ce tag, construit avec MANUAL_VERSION=<version> et publie un répertoire statique immuable. Le menu des versions est un petit manifeste de ces répertoires.