Hop til hovedindhold

Vedligehold denne manual

Kildekoden ligger i applikationsarkivet, så en adfærdsændring og dens dokumentation kan lande sammen. Genererede skærmbilleder publiceres til en Cloudflare R2-bucket under ét versioneret præfiks pr. manualversion og bliver aldrig commit'et til applikationstræet.

Rediger prosaen​

  1. Rediger eller tilføj den engelske MDX-fil under docs-site/docs.
  2. Opdater matchfilen for hver publiceret lokation under docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
  3. Tilføj en ny side til docs-site/sidebars.ts.
  4. Opdater docs-site/metadata/features.json, når dækningen ændres.
  5. Opdater de matchende poster i docs-site/metadata/surface-inventory.json. En flade bliver først verificeret, når dens aktuelle produktions-UI, prosa og skærmbillededækning alle er blevet gennemgået.
  6. Kør make manual_check.
  7. Gennemse produktionsbuildet lokalt med make manual_serve, herunder sprogvælger og alle lokaliserede ruter.

Valideringen kræver, at hvert publiceret oversættelsestræ indeholder de samme sidestier som det engelske kildetræ. Den afviser også oversatte sidekroppe, der er identiske med engelsk, så nye sider ikke i det stille kan udgives som uoversatte kopier. De offentlige engelske URL'er forbliver uændrede; andre sprog udgives under deres eget versionerede locale-præfiks.

Hold dækningslisten autoritativ​

Inventaret definerer V1's engelsk-manual-grænse: hver Beamer-side, hvert Indstillinger V2-blad og hver editor, og alle større arbejdsgange, der opretter eller væsentligt ændrer data eller tværgående konfiguration. Hver post registrerer sin ejende kildefil og et kildetekstanker. Valideringen fejler, hvis en af dem forsvinder, hvilket tvinger en rute- eller UI-ændring til at opdatere manual-revisionen i stedet for at efterlade en usynlig, forældet række.

Dækningsstater har bevidst strenge betydninger:

  • Planlagt betyder, at fladen er kendt, men stadig mangler fuld dækning.
  • Dokumenteret betyder, at der findes nyttig prosa, men at skærmbilleder fra den aktuelle produktion eller en fuld nøjagtighedsgennemgang stadig mangler.
  • Verificeret betyder, at den relevante funktionsside er verificeret og understøttet af registrerede produktionsskærmbilleder.

Kør npm --prefix docs-site run coverage:complete som udgivelsesgate. Den fejler, indtil alle inventariserede flader er verificeret; almindelige inkrementelle manual-builds fortsætter med at rapportere de resterende tal uden at blokere emneafgrænsede commits.

Tilføj et screenshot-case​

  1. Tilføj eller genbrug en deterministisk Flutter screenshot-sele.
  2. Registrer sagen og dens fire kildebilleder i docs-site/metadata/screenshot-cases.json.
  3. Læg synlig fixturetekst bag manualScreenshotText(...) for hvert understøttet sprog, når den ikke allerede leveres af appens lokaliseringsfiler.
  4. Optag hvert sprog i den gitignorerede lokale staging-mappe (make manual_screenshots); CI publicerer resultatet til R2-bucketen.
  5. Generer og valider mediemanifestet.
  6. Henvis til sagen med <ManualScreenshot caseId="…" alt="…" /> på hver sprogsideside.

Alle appskærmbilleder på en forfattet side skal bruge ManualScreenshot. Direkte links til skærmbilledmedier — gamle lotti-docs-billeder eller selve R2-bucketen — fejler manualvalideringen, fordi de ikke kan følge det globale Mobile/Desktop-valg eller manualens lyse/mørke tema.

Hver automatiseret sag skal levere mobile-light-, mobile-dark-, desktop-light- og desktop-dark-varianter på hvert udgivet sprog. Manual-komponenten vælger det matchende sprog og tema. Når Mobile/Desktop ændres på et billede, opdateres alle skærmbilleder straks, og valget bevares på tværs af sider og åbne manualfaner.

Udgiv en version​

Manualens kilde kopieres ikke for hver appversion. Appens release-tag bevarer allerede den præcise tilstand. Hvert release-tag udgiver automatisk manualen for sin version: Hvis manualens sider, skærmbilledtests eller demodata er ændret siden forrige release, bygger CI siden og tager skærmbillederne fra tagget; ellers genbruger den nye version forrige releases snapshot. Release-snapshots overskrives aldrig. Appen åbner manualen for sin egen version. De ti nyeste release-snapshots forbliver online, og et link til enhver anden version lander på den nyeste release. Du kan også udgive en release-manual i hånden med en workflow-kørsel, der angiver marketingversionen. Versionsvælgeren læser et livekatalog, der skrives ved hver udrulning, så også ældre manualer viser de senere releases.