Întrețineți acest manual

Sursa se află în depozitul aplicației, astfel încât o schimbare de comportament și documentația ei pot fi livrate împreună. Capturile de ecran generate sunt publicate într-un bucket Cloudflare R2, sub câte un prefix versionat pentru fiecare versiune a manualului, și nu sunt niciodată incluse în arborele aplicației.

Editați textul

1. Editați sau adăugați fișierul MDX în engleză din docs-site/docs.
2. Actualizați fișierul corespunzător pentru fiecare limbă publicată din docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
3. Adăugați pagina nouă în docs-site/sidebars.ts.
4. Actualizați docs-site/metadata/features.json când se schimbă acoperirea.
5. Actualizați intrările corespunzătoare din docs-site/metadata/surface-inventory.json. O suprafață devine verificată numai când interfața ei curentă din producție, textul și acoperirea prin capturi au fost toate revizuite.
6. Rulați make manual_check.
7. Revizuiți local buildul de producție cu make manual_serve, inclusiv selectorul de limbă și fiecare rută localizată.

Validarea impune ca fiecare arbore de traduceri publicat să conțină aceleași căi de pagină ca arborele-sursă englez. De asemenea, respinge corpuri de pagină traduse care sunt identice cu engleza, astfel încât paginile noi să nu poată fi livrate discret fără traducere. URL-urile publice în engleză rămân neschimbate; celelalte limbi sunt publicate sub propriul prefix de limbă cu versiune.

Păstrați inventarul de acoperire ca autoritate

Inventarul definește limita manualului englez V1: fiecare pagină Beamer, fiecare frunză sau editor Settings V2 și fiecare flux major care creează ori modifică în mod semnificativ date sau configurare transversală. Fiecare intrare înregistrează fișierul-sursă proprietar și o ancoră de text-sursă. Validarea eșuează dacă oricare dintre ele dispare, obligând o schimbare de rută sau UI să actualizeze auditul manualului, în loc să lase un rând învechit invizibil.

Stările de acoperire au sensuri intenționat stricte:

• Planificată înseamnă că suprafața este cunoscută, dar încă nu are acoperire completă.
• Documentată înseamnă că există text util, însă lipsesc capturi actuale din producție sau o revizuire completă a corectitudinii.
• Verificată înseamnă că pagina funcției relevante este verificată și susținută de capturi din producție înregistrate.

Rulați npm --prefix docs-site run coverage:complete pentru pragul de lansare. Comanda eșuează până când fiecare suprafață inventariată este verificată; buildurile obișnuite incrementale ale manualului continuă să raporteze numerele rămase fără a bloca commiturile dedicate câte unui subiect.

Adăugați un caz de captură de ecran

1. Adăugați sau reutilizați un harness determinist Flutter pentru capturi de ecran.
2. Înregistrați cazul și cele patru imagini-sursă în docs-site/metadata/screenshot-cases.json.
3. Puneți textul fixture vizibil în spatele manualScreenshotText(...) pentru fiecare limbă acceptată, când nu este deja furnizat de fișierele ARB ale aplicației.
4. Capturați fiecare limbă în directorul local de pregătire ignorat de git (make manual_screenshots); CI publică rezultatul în bucketul R2.
5. Generați și validați manifestul media.
6. Referiți cazul prin <ManualScreenshot caseId="…" alt="…" /> în fiecare pagină de limbă.

Fiecare captură a aplicației într-o pagină creată trebuie să folosească ManualScreenshot. Legăturile directe către mediile capturilor de ecran — imagini vechi din lotti-docs sau chiar bucketul R2 — eșuează validarea manualului, fiindcă nu pot urma alegerea globală Mobil/Desktop sau tema luminoasă/întunecată a manualului.

Fiecare caz automatizat trebuie să ofere variante mobil-luminos, mobil-întunecat, desktop-luminos și desktop-întunecat pentru fiecare limbă publicată. Componenta manualului alege limba și tema potrivite. Schimbarea Mobil/Desktop pentru orice imagine actualizează imediat toate capturile și persistă între pagini și file de manual deschise.

Publicați o lansare

Sursa manualului nu este copiată pentru fiecare versiune a aplicației. Eticheta de lansare a aplicației păstrează deja sursa exactă. Publicarea este o rulare manuală a fluxului de lucru, cu versiunea de marketing și cu implementarea activată: CI determină cea mai recentă etichetă de aplicație a acelei versiuni, construiește site-ul și catalogul său de capturi de ecran din etichetă, încarcă ambele într-un spațiu de stocare versionat imuabil și reimplementează site-ul cu toate versiunile una lângă alta. Instantaneele de lansare nu sunt niciodată suprascrise. Selectorul de versiuni citește un catalog live scris la fiecare implementare, astfel încât manualele mai vechi listează și lansările apărute după ele.