Zdůvodnění
Distribuční model je učebnicový tvar selhání, které tento repozitář existuje, aby zachytil. Týž fakt — že platforma je podporována — musí platit v matici release buildu, v cílové tabulce instalátoru, v tabulce platforem v dokumentaci, na webu a ve všem, co nástroj říká sám o sobě. Zapsaný pětkrát je do jednoho release nesprávný: tag sestaví pět artefaktů a instalátor nabízí šest, nebo dokumentace slibuje platformu, kterou nic nesestavilo, a selhání objeví člověk, který nástroj nemůže nainstalovat.
Cena kopií není ani jen nepořádek. Je v tom, že přidání platformy přestane být jednou úpravou a stane se kontrolním seznamem, a kontrolní seznam je věc, kterou spěchající člověk dokončí jen částečně.
Požadované chování
share/distribution.yaml je jediný model: binárka, repozitář, z něhož release vycházejí, kanonická URL a výchozí hodnoty instalátoru, funkce pro pojmenování archivu a každý cíl s operačním systémem, architekturou, knihovnou C, Rust target tripletem, stavem a runnerem, na němž jej release buildí. Cíl, který nedeklaruje, pro nic neexistuje.
Každý další povrch z něj vychází nebo je proti němu kontrolován:
- release build matrix je
docs/generated/distribution-matrix.json, generovaná z modelu; workflow ji čte a neuvádí žádný runner ani platformu; - tabulka platforem instalátoru je generovaná oblast uvnitř
share/install/install.sh.in; chování kolem ní je psáno ručně a neuvádí žádnou platformu; - tabulka platforem v instalační příručce se generuje do
docs/INSTALL.mdzshare/install/INSTALL.md.in; - názvy artefaktů pocházejí z jediné funkce,
Target::artifact_name, kterou každý volající dosáhne přesmajordomus distribution artifact; žádný skript, workflow ani dokument je neskládá; - web vykresluje
site/data/registry/distribution.json, generovaný z modelu; - veřejná metadata release se generují ze záznamů release v
.ai/repo/releases/a stabilní ukazatel se z nich odvozuje při každém generování a nikde se nepíše ručně; - zdokumentovaný instalační příkaz se skládá z částí modelu a doslova se objevuje v
README.mdadocs/INSTALL.md, což se kontroluje, ne předpokládá.
Ze stejného modelu plynou dva další invarianty. Release publikuje artefakt pro každý cíl, který model označuje jako podporovaný, jinak se nepublikuje: částečný release se odmítne při zaznamenání, a neobjeví se, až se někdo nemůže nainstalovat. A veřejný instalační návod smí jmenovat jen testovanou cestu: vlastní případy instalátoru instalují skutečný archiv ze skutečných metadat a release pipeline instaluje release, který právě publikovala, z URL, které dokumentace tiskne.
Chování při selhání
majordomus distribution validate skončí kódem 10 a pojmenuje každé porušení vlastních invariancí modelu a každý nesoulad mezi záznamem releasu a modelem. majordomus generate --target distribution --check skončí kódem 10 a pojmenuje každou projekci, která zaostala, a spouští ji just derive-check, kontrola CI, kterou provádí úloha site, a pipeline releasu před sestavením čehokoli. scripts/release-record odmítne zapsat záznam, kterému chybí podporovaný cíl. scripts/release-version --check odmítne strom, v němž autorita — verze v manifestu crate — to, co vypisuje shellový nástroj, a tag neuvádějí jednu verzi.
Ověření
test/cases/84_distribution_model.sh dokazuje invarianty mutací: cíl přidaný do kopie modelu se musí objevit v instalátoru, matici a průvodci a musí způsobit selhání commitnutých projekcí --check; duplicitní id, duplicitní trojice a základní URL jiné než HTTPS musí být každé odmítnuto jménem. test/cases/85_installer.sh instaluje skutečný archiv ze skutečných metadat přes skutečné spojení a drží každou cestu selhání v tom, že předchozí instalace zůstane funkční. test/cases/86_installer_platform.sh řeší každou deklarovanou platformu z jednoho stroje a drží odmítnutí v tom, že jmenují, co zjistila. test/cases/87_release_pipeline.sh drží workflow u modelu, který adaptuje. Návrh je docs/DISTRIBUTION.md.