Zum Hauptinhalt springen

Dieses Handbuch pflegen

Der Quelltext liegt im App-Repository, damit eine Verhaltensänderung gemeinsam mit ihrer Dokumentation landen kann. Erzeugte Screenshots liegen im Schwester-Repository lotti-docs und werden nie in den App-Baum eingecheckt.

Texte bearbeiten​

  1. Bearbeite oder ergänze englische MDX-Dateien unter docs-site/docs.
  2. Aktualisiere die gleichnamige Datei jeder veröffentlichten Sprache unter docs-site/i18n/<sprache>/docusaurus-plugin-content-docs/current.
  3. Ergänze neue Seiten in docs-site/sidebars.ts.
  4. Aktualisiere docs-site/metadata/features.json, wenn sich die Abdeckung ändert.
  5. Aktualisiere die passenden Einträge in docs-site/metadata/surface-inventory.json. Eine Oberfläche ist erst verifiziert, wenn produktive UI, Text und Screenshots geprüft wurden.
  6. Führe make manual_check aus.
  7. Prüfe den Produktions-Build lokal mit make manual_serve – einschließlich Sprachumschalter und aller lokalisierten Routen.

Die Validierung verlangt für jede veröffentlichte Übersetzung dieselben Seitenpfade wie im englischen Quellbaum. Sie lehnt außerdem Seiten ab, deren Inhalt mit dem englischen Original identisch ist. Neue Seiten können dadurch nicht unbemerkt als unübersetzte Kopie erscheinen. Die öffentlichen englischen URLs bleiben unverändert; andere Sprachen werden unter ihrem eigenen versionierten Sprachpräfix veröffentlicht.

Die Abdeckungsinventur verbindlich halten​

Die Inventur definiert den Umfang des V1-Handbuchs: jede relevante Seite, jedes Settings-V2-Blatt oder jeden Editor und jeden wichtigen Ablauf, der Daten oder übergreifende Konfiguration erstellt oder wesentlich ändert. Jeder Eintrag nennt Quelldatei und Textanker. Verschwindet eines davon, schlägt die Validierung fehl. Routen- oder UI-Änderungen können dadurch keine unsichtbar veraltete Zeile hinterlassen.

Die Zustände haben strenge Bedeutungen:

  • Geplant: Oberfläche bekannt, Abdeckung noch unvollständig.
  • Dokumentiert: Nützlicher Text vorhanden, aktuelle produktive Screenshots oder vollständige Genauigkeitsprüfung fehlen noch.
  • Verifiziert: Feature-Seite geprüft und durch registrierte produktive Screenshots belegt.

npm --prefix docs-site run coverage:complete ist die Release-Schranke. Sie schlägt fehl, solange eine inventarisierte Oberfläche nicht verifiziert ist. Normale inkrementelle Builds melden die Restzahlen, ohne thematisch kleine Commits zu blockieren.

Einen Screenshot-Fall hinzufügen​

  1. Ergänze oder verwende einen deterministischen Flutter-Screenshot-Harness.
  2. Registriere Fall und vier Quelldateien in docs-site/metadata/screenshot-cases.json.
  3. Hinterlege sichtbare Demo-Texte über manualScreenshotText(...) für jede unterstützte Sprache, wenn sie nicht bereits aus der App-Lokalisierung stammen.
  4. Erfasse mit make manual_screenshots alle Sprachen in ../lotti-docs – niemals in diesem Repository.
  5. Erzeuge und validiere das Medienmanifest.
  6. Referenziere den Fall mit <ManualScreenshot caseId="…" alt="…" /> in jeder Sprachseite.

Jeder App-Screenshot muss ManualScreenshot verwenden. Direkte Links auf alte lotti-docs-Bilder scheitern an der Validierung, weil sie weder der globalen Mobil/Desktop-Auswahl noch Hell/Dunkel oder der Dokumentsprache folgen.

Jeder automatisierte Fall liefert Mobil-Hell, Mobil-Dunkel, Desktop-Hell und Desktop-Dunkel für jede veröffentlichte Sprache. Die Komponente wählt Sprache und Design automatisch. Eine Änderung von Mobil/Desktop an einem Bild aktualisiert sofort alle Screenshots und bleibt über Seiten und offene Tabs hinweg erhalten.

Ein Release veröffentlichen​

Der Quelltext wird nicht für jede App-Version kopiert. Das App-Release-Tag bewahrt bereits den exakten Stand. CI checkt dieses Tag aus, baut mit MANUAL_VERSION=<version> und veröffentlicht ein unveränderliches statisches Verzeichnis. Das Versionsmenü ist ein kleines Manifest dieser Verzeichnisse.