Vydání příručky je deklarovaný strom lokalizace, postavený ze stromu, který popisuje

149. Edice příručky je deklarovaný strom lokalizace, sestavený ze stromu, který popisuje

Kontext

Dne 2026-10-12 existovala příručka tohoto produktu v češtině: sedmasedmdesát kapitol, vestavěný čtenář každého dokumentu, rozhodnutí, pravidla, tvrzení a případu užití, mapa a toky vypočtené z docs/generated/graph.json a panel pod každou kapitolou jmenující, na čem kapitola stojí. Žila v adresáři mimo tento repozitář a skript ji na jednom stroji znovu sestavoval z origin/master. Toto uspořádání mělo tři vady, všechny tutéž vadu:

• Nešlo ho udržet ve shodě se stromem. Jeho build odmítl kapitolu, jejíž kotva z grafu zmizela, a nic ten build nespustilo, když se strom změnil. Přejmenování tu handbook tiše rozbilo a zjistilo se to, až ho někdo příště znovu sestavil.
• Nikdo jiný ho nemohl sestavit. Generátor četl cestu na jednom disku.
• Bylo to mimo každou kontrolu, každé review a každý záznam, které tento repozitář má.

Při přesunu narazilo na project.english-only. Verze 2 tohoto pravidla (ADR 0077) připouští jazyk čtenáře přesně na jednom místě, na stránce pod site/content-src/, která deklaruje svůj vlastní jazyk. Příručka je stejná populace, adresovaná obsahem čtenáři, a není stránkou: edice jsou texty, widgety, build a testy v prohlížeči.

Vlastník nařídil přesun a změnu pravidla dne 2026-10-12 těmito slovy: „move it somewhere in the repository to have it inferred, derived, generated, in sync with the repo, document it, enforce it via .ai, keep in sync; amend the ADRs, the rules, the enforcement; my clearance, the architectural change is from me.“

Rozhodnutí

1. Příručka žije v handbook/. handbook/build.py a tři odvozeniny vedle ní (derive_data.py, corpus.py, graph.py) jsou pracovní artefakty a jsou anglicky. Čtou strom, ve kterém jsou, a nic jiného: co git sleduje, docs/generated/graph.json, registr, model CI, historii. Nic se nestahuje.
2. Edice je jeden adresář, handbook/<language>/, s edition.toml, který deklaruje daný jazyk. Její texty se píší ručně v tomto jazyce. Každý obrázek, seznam, graf a panel v ní je odvozen.
3. project.english-only přechází na verzi 3 a připouští edici jako druhé místo pro populaci, kterou pojmenovala verze 2. Deklarace je edition <directory> <language> <why> v scripts/ci/english-only-allow.txt a je oboustranná jako překlad: adresář je handbook/<language> a jeho vlastní edition.toml říká tentýž jazyk. Edice deklarovaná kdekoli jinde nebo pro adresář, který říká něco jiného, je odmítnuta.
4. Každá kapitola deklaruje, na čem stojí v chapter_sources.py vydání: dokumenty, funkce produktu, moduly schopností, příkazy, rozhodnutí, pravidla, tvrzení. Build vyřeší každý odkaz proti grafu repozitáře a odmítne, s kódem 10, odkaz, který graf už nenese, kapitolu, která nic necituje, popisek žádající obrázek, který data nemají, a odvozená data, jejichž tvar se pod stránkou změnil.
5. Build je kontrola. handbook-check spouští python3 handbook/build.py --check při každé změně, takže změna, která odstraní nebo přejmenuje to, na čem kapitola stojí, selže tam, kde vzniká. Sestavená stránka je ignorovaný výstup pod target/handbook/; necommituje se.

Zamítnuté alternativy

• Stránky webu. To se do verze 2 vejde bez změny a znamená to přepsat příručku jako stránky Zola a přesunout její generátor do šablon webu. Web je jeden konzument vydání, ne jeho zdroj; publikace vydání na webu je pozdější projekce target/handbook/, rozhodnutá s vlastníky samotného webu.
• Jen anglická příručka. Čtenář, pro kterého byla tato napsána, čte česky, a anglická by opakovala docs/. Druhé vydání je jeden další adresář pod tímto rozhodnutím, nikoli jiný mechanismus.
• Ponechat ho venku a vendorovat kotvy. Kopie seznamu kotev v tomto repozitáři by byl tvar dvě-místa-jeden-fakt, který ADR 0004 odmítá.
• Commitovat sestavenou stránku. Jsou to čtyři megabajty odvozeného výstupu, které by kolidovaly při každém přistání.

Důsledky

• Změna zde, která odstraní dokument, funkci, modul, příkaz, rozhodnutí, pravidlo nebo tvrzení, které kapitola jmenuje, způsobí selhání handbook-check a oprava je ve stejné změně: upravit kapitolu, nebo věc ponechat.
• Vlastní soubory edice jsou vyňaty z testu abecedy a z ničeho jiného. Review je pořád čte.
• Web zatím nenabízí příručku a nenabízí přepínač jazyků. Obojí jsou projekce toho, co toto rozhodnutí vkládá do stromu, a nerozhoduje se tu o nich.
• Prohlížečové testy edice (handbook/cs/tests/) potřebují prohlížeč a nejsou součástí kontroly; kontrola dokazuje sestavení a test/cases/2984 dokazuje kontrolu mutací.
• Stav je proposed. Vlastník změnu nařídil; zapsat accepted je úkon vlastníka.