Ga naar hoofdinhoud

Onderhoud deze handleiding

De bron staat in de applicatierepository, zodat een gedragswijziging en de bijbehorende documentatie samen kunnen landen. Gegenereerde schermafbeeldingen worden gepubliceerd naar een Cloudflare R2-bucket onder één geversioneerd prefix per handleidingsversie en worden nooit in de applicatierepository gecommit.

Bewerk proza​

  1. Bewerk of maak het Engelse MDX-bestand onder docs-site/docs.
  2. Werk het overeenkomstige bestand bij voor elke gepubliceerde locale onder docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
  3. Voeg een nieuwe pagina toe aan docs-site/sidebars.ts.
  4. Werk docs-site/metadata/features.json bij wanneer de dekking verandert.
  5. Werk de bijbehorende vermeldingen in docs-site/metadata/surface-inventory.json bij. Een oppervlak wordt pas geverifieerd wanneer de huidige productie-UI, het proza en de screenshotdekking allemaal zijn beoordeeld.
  6. Voer make manual_check uit.
  7. Bekijk de productiebuild lokaal met make manual_serve, inclusief de taalkiezer en elke gelokaliseerde route.

Validatie vereist dat elke gepubliceerde vertaalboom dezelfde paginapaden bevat als de Engelse bronboom. Ze verwerpt ook vertaalde pagina's waarvan de tekst identiek is aan het Engels, zodat nieuwe pagina's niet stilletjes als onvertaalde kopieën kunnen verschijnen. De openbare Engelse URL's blijven ongewijzigd; andere talen worden gepubliceerd onder hun eigen geversioneerde locale-prefix.

Houd de dekkingsinventaris gezaghebbend​

De inventaris definieert de grens van de Engelse V1-handleiding: elke Beamer-pagina, elk Instellingen V2-blad of elke editor, en elke belangrijke workflow die gegevens of overkoepelende configuratie aanmaakt of wezenlijk verandert. Elke vermelding registreert het eigen bronbestand en een anker in de brontekst. Validatie mislukt zodra een van beide verdwijnt, waardoor een route- of UI-wijziging de audit van de handleiding moet bijwerken in plaats van een onzichtbare verouderde rij achter te laten.

Dekkingsstatussen hebben bewust strikte betekenissen:

  • Gepland betekent dat het oppervlak bekend is, maar nog geen volledige dekking heeft.
  • Gedocumenteerd betekent dat er bruikbaar proza bestaat, maar dat actuele productiescreenshots of een end-to-end-nauwkeurigheidsbeoordeling nog ontbreken.
  • Geverifieerd betekent dat de betreffende functiepagina is geverifieerd en wordt ondersteund door geregistreerde productiescreenshots.

Voer npm --prefix docs-site run coverage:complete uit voor de releasepoort. Die mislukt totdat elk geïnventariseerd oppervlak is geverifieerd; gewone incrementele handleidingbuilds blijven de resterende aantallen rapporteren zonder commits ter grootte van één onderwerp te blokkeren.

Voeg een screenshot-case toe​

  1. Voeg een deterministisch Flutter-screenshotharnas toe of hergebruik er een.
  2. Registreer de case en de vier bronafbeeldingen in docs-site/metadata/screenshot-cases.json.
  3. Plaats zichtbare fixture-teksten achter manualScreenshotText(...) voor elke ondersteunde locale wanneer de app-lokalisatiebestanden ze nog niet leveren.
  4. Leg elke locale vast in de door git genegeerde lokale stagingmap (make manual_screenshots); CI publiceert het resultaat naar de R2-bucket.
  5. Genereer en valideer het mediamanifest.
  6. Verwijs op elke taalpagina naar de case met <ManualScreenshot caseId="…" alt="…" />.

Elke app-screenshot op een geschreven pagina moet ManualScreenshot gebruiken. Directe koppelingen naar screenshotmedia — oude lotti-docs-afbeeldingen of de R2-bucket zelf — mislukken bij de validatie van de handleiding, omdat ze de algemene Mobile/Desktop-keuze of het light/dark-thema van de handleiding niet kunnen volgen.

Elke geautomatiseerde case moet mobiel-licht, mobiel-donker, desktop-licht en desktop-donker leveren in elke gepubliceerde locale. Het handleidingcomponent kiest de bijpassende taal en het thema. Mobile/Desktop wijzigen op één afbeelding werkt elke schermafbeelding onmiddellijk bij en blijft behouden over pagina's en geopende handleidingstabbladen heen.

Publiceer een release​

De bron van de handleiding wordt niet voor elke app-versie gekopieerd. De app-releasetag behoudt de exacte bron al. Publiceren is een handmatig gestarte workflow-run met de marketingversie en deploy ingeschakeld: CI zoekt de nieuwste app-tag van die versie op, bouwt de site en de bijbehorende screenshotcatalogus vanaf de tag, uploadt beide naar onveranderlijke geversioneerde opslag en deployt de site opnieuw met alle versies naast elkaar. Release-snapshots worden nooit overschreven. De versiedropdown leest een live catalogus die bij elke deploy wordt geschreven, dus oudere handleidingen tonen ook de releases die na hen verschenen.