85. Verze se píše jednou, v manifestu crate, a dodává se shellovému nástroji jako generovaná projekce
Stav: navrženo. Přijetí je úkon správce. Tento záznam mění ADR 0029, ADR 0019 a ADR 0051 v jediném ohledu, v němž každé z nich uvádí verzi dvakrát; vše ostatní v nich platí.
Kontext
Požadavek vlastníka byl prostý: zajistit, aby existovalo jedno místo, kde se zachází s verzováním. Repozitář je neměl. Verze produktu byla psána na dvou místech:
apps/majordomus-cli/Cargo.toml version = "0.8.0" the crate's version
bin/majordomus MJ_VERSION="0.8.0" what the shell tool printsADR 0029 dalo dvojici jednoho zapisovatele, release bump, a scripts/release-version --check dokazoval, že se shodují. Jediný zdroj zamítlo ze čtyř důvodů (ADR 0029, Collapsing the version to a single source):
- (a) nainstalovaný strom nemá
Cargo.toml, takže ho shellový nástroj za běhu nemůže přečíst; - (b) build skript zapisující
MJ_VERSIONdobin/majordomusby udělal ze sledovaného souboru výstup sestavení; - (c) crate se kompiluje dřív, než existuje shell nástroj;
- (d) generovat jedno z druhého za běhu je závislost za běhu mezi dvěma programy, které se dodávají odděleně.
Každý důvod platí o alternativě, kterou jmenuje. Žádný neplatí proti generované projekci dodávané v distribuci a projekce je způsob, jakým tento repozitář uvádí každý další odvozený fakt.
Rozhodnutí
Verze se píše na přesně jednom místě: [package] version v apps/majordomus-cli/Cargo.toml. Každé další její uvedení je z toho řádku odvozeno a kontrolováno, nebo je záznamem verze, která byla vydána:
| Výrok | Třída | Zapsal | Drží |
|---|---|---|---|
apps/majordomus-cli/Cargo.toml [package] version | autorské — jediné místo | majordomus release bump | release analyze, version-surface |
crate::VERSION (clap, MCP, OpenAPI, health, ledger) | zkompilováno | cargo | vlastní testy crate |
share/version.txt | generovaná projekce | majordomus generate (cíl distribution) | generate --check, release-version --check, release-verify |
apps/majordomus-cli/Cargo.lock, vstup crate | odvozeno pravidlem cargo | release bump, vedle manifestu | cargo build --locked, release-check 2b |
| razítka generátorů, changelog, verze webu | vygenerováno | majordomus generate, scripts/derive | generate --check, derive-check |
.ai/repo/releases/*.yaml, latest.json, RELEASE.json | záznamy vydané verze | pipeline release | release-check, instalátor |
bin/majordomus | žádné prohlášení — čte se share/version.txt | — | případ 484 |
Shellový nástroj čte projekci, vedle sebe sama. share/version.txt je typovaný artefakt generate (ArtifactFormat::Text, indexovaný v docs/generated/artifacts.json, merge=derived), generovaný pod stejnou ochranou, jakou používá projekce designu — sdílení i crate jsou v tomto repozitáři — takže spravovaný repozitář ho nikdy nedostane. Jeho hodnotou je autorita čtená přímo (release::version::declared). bin/majordomus čte svůj řádek version= při startu samotnými builtiny shellu, z bin/../share/version.txt, a nikdy z MAJORDOMUS_SHARE, které pojmenovává data ke čtení, ne identitu programu, který čte. Distribuce bez něj končí kódem 12 a jmenuje soubor. Každý archiv už dodává share/ celé, takže checkout, instalovaný strom, instalace submodulu i odkládací adresář instalátoru čtou verzi jednou cestou kódu.
Jeden zapisovatel, jeden autorský řádek. release bump přepíše řádek s verzí v manifestu a udrží krok se záznamem majordomus-cli v zámku — nejde o druhou deklaraci, ale o záznam cargo, který zapisovatel udržuje, protože zámek, který zůstane pozadu, shodí každý build --locked, včetně launcheru, který používají git hooky a MCP server. bin/majordomus už nezapisuje. Projekce i každý stamp vycházejí z scripts/derive.
Jeden čtenář autority na jazyk. release::version::declared v Rustu (ochrana cizí generace příkazu generate čte přes něj), scripts/release-version v shellu. Gate a případy se ptají jich; žádný nečte manifest sám.
Druhé prohlášení odmítá typ. release::version::diagnose v modulu release hlásí:
version-stated-by-hand(chyba) — nosič ve tvaru verze zapsaný ručně vbin/,lib/,scripts/neboshare/mimo generovaný artefakt: přiřazení jménu končícímuversion(shell, TOML, JavaScript nebo Python), členversion:nebo"version":nebomajordomus X.Y.Zproduktu;projection-stale(varování) — projekce zaostává za manifestem nebo chybí: stav, který zanechá každé zvýšení verze, dokud neproběhne odvození. Varování, protože ho odmítágenerate --check, a zapisovatel, který by odmítal vlastní neodvozený stav, by nemohl zvýšení opravit;writers-disagree(chyba) — projekce je před manifestem nebo s ním nesouvisí: verze, kterou nezapisuje žádné odvození.
release analyze je nese ve svém plánu na každém povrchu; release version je vypíše a skončí s kódem 10; kontrola version-authored-once (úloha struktury, always: true) spouští bin/majordomus-cli release version. Veřejná jména polí zprávy o verzi a plánu (tool, agree, tool_version, writers_agree) zůstávají a předefinovávají se jako projekce a zda je aktuální, takže se nehýbe smlouvou žádného volajícího.
Proč čtyři důvody už neplatí
- (a) žádné
Cargo.tomlpři instalaci. Projekce se dodává vshare/, vedle nástroje. - (b) sledovaný soubor jako výstup sestavení. Je to cíl
generate, jako zhruba 130 dalších projekcí, kterégenerate --checkdrží, ne vedlejší efektcargo build. - (c) crate zkompilovaný jako první. Pořadí nezáleží:
generateodmítne běžet s executable jiné verze (refuse_foreign_generation) a hodnota projekce se čte z manifestu, ne z executable. - (d) závislost za běhu mezi programy. Žádná neexistuje. Shell nástroj čte textový soubor, který nese jeho vlastní distribuce.
Zamítnuté alternativy
Ponechat literál a kontrolovat jej. To je stav, který toto nahrazuje — paralelní ručně vedené tvrzení, které požadavek zakazuje.
Generovaná oblast uvnitř bin/majordomus. Manifest artefaktů indexuje celé soubory podle hashe, takže půlka spustitelného souboru nemůže být typovaným artefaktem; .gitattributes nemůže označit půlku souboru jako merge=derived; a generate by zapisoval do bin/.
Číst Cargo.toml v checkoutu a RELEASE.json po instalaci. Dvě cesty kódu pro jeden fakt, fork na horké cestě hooku a žádná odpověď v instalaci jako submodul.
Zeptat se spustitelného souboru (libexec/majordomus-cli --version). Jeden proces na volání a v checkoutu může launcher nejdřív sestavit.
Napsat verzi v share/version.txt a zkompilovat ji pomocí include_str!. Zanechalo by to zástupný symbol v Cargo.toml a Cargo.lock a image nasazení do své build fáze kopíruje jen crate.
Plošné prohledání repozitáře na řetězec aktuální verze. Revize návrhu jej změřila proti nejpravděpodobnějším dalším verzím: selhává na doc testech, fixturách a rozsahu verzí závislosti, které náhodou sdílejí číslo, a grep -w nevidí tvar s předponou v. Typovaná diagnostika kontroluje deklarované tvary tam, kde žijí soubory samotného nástroje, a generate --check drží vše generované.
Důsledky
Zvýšení verze je jedna úprava jednoho souboru, provedená jedním příkazem, a odvození:
bin/majordomus-cli release bump # the manifest's line, and the lock's own entry
scripts/derive # builds, then projects share/version.txt and every stampscripts/release-version --check se nyní ptá na otázku, kterou generate --check nechává otevřenou — ne zda je soubor aktuální, ale zda nástroj autoritu skutečně vypisuje — a plán releasu, release-verify na každém archivu a vlastní kontrola instalátoru se jí na dodaném nástroji ptají beze změny.
Distribuce, která ztratila share/version.txt, se při startu zastaví pro každý příkaz, včetně hooků. To je zamýšleno: nástroj, který nedokáže říct, čím je, nemá co odpovídat na cokoli jiného. Každá fixture v sadě, která kopíruje bin/, kopíruje také share/ a archivní profil context soubor ponechává, ačkoli jiné projekce vypouští.
package.json a package-lock.json ztratily zatoulané "version": "0.1.0" soukromého balíčku webu, které nic nečetlo a které odporovalo jedinému místu.
Co to drží: test/cases/484_the_version_is_authored_once.sh — každá jeho sekce spuštěná proti stromu před touto změnou a tam selhávající — případ 103 nad zapisovatelem a reportem, případ 112 nad změřeným zvýšením, unit a doc testy release/version.rs, scripts/ci/release-check, scripts/release-version --check a kontrola version-authored-once.