Changelog se skládá a verze se píše jednou

Zdůvodnění

Changelog je klasický soubor, který je správný v den, kdy se napíše. Všechno v něm už je v repozitáři, který jej vytvořil — který tag byl publikován a z jakého commitu, která rozhodnutí padla a kdy, co o sobě každý commit tvrdil — a soubor existuje jen proto, že ty tři zdroje nic nespojovalo. Píše se tedy ručně, a pak už ne: chybí záznam o releasu, na který nikdo nevzpomněl, a čtenář nepozná klidný release od zapomenutého, protože udržovaný changelog neříká nic o tom, co vynechal.

Verze měla stejný tvar o úroveň níž. Byla jediným faktem, který musí uvádět oba dodávané programy, a byla zapsána dvakrát — v manifestu crate a jako literál v shellovém nástroji — s kontrolou, která obě porovnávala, a od verze 1 tohoto pravidla s jedním zapisovačem, který zvyšoval obě. Uvedený důvod byl skutečný: nainstalovaný strom nemá Cargo.toml, takže shellový nástroj nemohl za běhu číst manifest. Mohl však číst jeho projekci a projekce je způsob, jakým tento repozitář uvádí každý jiný odvozený fakt. Verze 2 tohoto pravidla to přesně dělá: verze se píše na jednom místě a shellový nástroj čte generovaný soubor, který nese jeho vlastní distribuce (ADR 0085).

Požadované chování

Changelog se skládá, nikdy se nevede ručně. Jeho zdroje jsou ty, které repozitář už uvádí, a čte je a nic jiného:

  .ai/repo/releases/*.yaml   what shipped, when, from which commit, with which artifacts
  .ai/repo/adrs/*.md         the decisions, placed by the date each carries
  git log <from>..<to>       everything that has no object of its own

• záznam release vložený do vrstvy se stane sekcí, aniž by se kdekoli upravoval dokument, šablona, index nebo seznam;
• commit, jehož předmět nedodržuje žádnou konvenci, se nese pod Other, nikdy se nevypouští — changelog, který tiše vynechá, co neumí zařadit, lže vynecháním a vynechání je pro čtenáře z principu neviditelné;
• co nešlo přečíst, se uvede, ne skryje: mělký klon, záznam pojmenovávající commit, který tento klon nemá, rozsah, který nic nedá;
• žádný soubor pojmenovaný CHANGELOG se nepíše ručně, v kořeni repozitáře ani pod docs/. Psaná podoba je generovaný artefakt pod docs/generated/ a stránka, která tento dokument vykresluje, je jeho projekce, ne druhá kopie.

Verze se píše jednou, jednou se promítá pro shellový nástroj, zaznamenává ji pipeline a zapisuje ji jeden příkaz. Každé její vyjádření je jedním z těchto a nic jiného:

• bin/majordomus neuvádí žádnou verzi. Čte řádek version= souboru share/version.txt vedle sebe, nikdy z MAJORDOMUS_SHARE, a distribuce bez tohoto souboru odmítne nastartovat, místo aby hádala.
• Jeden čtenář autority na jazyk: release::version::declared v Rustu a scripts/release-version v shellu. Kontrola, skript nebo případ, který potřebuje verzi, se zeptá jednoho z nich, nebo se zeptá bin/majordomus version; žádný nezpracovává manifest znovu.
• majordomus release bump je jediný zapisovatel. Přepíše řádek verze v manifestu a vlastní záznam majordomus-cli v zámku — záznam cargo, udržovaný v souladu, aby další build --locked přežil — a nic jiného; je idempotentní, přečte obojí zpět a odmítne vymyslet verzi, kterou nedostal nebo nedokáže odvodit. Projekce a každé razítko z scripts/derive vyplývají. Jakou verzi zapíše, není jeho vlastní úsudek: rozhoduje o tom project.the-version-is-measured z veřejné smlouvy.
• package.json neuvádí žádnou verzi: soukromý balíček webu není produkt a druhý řetězec verze tam odporoval jedinému místu.

Zvýšení verze je mutace repozitáře. Zapisuje sledované soubory, takže na ni neodpovídá žádná schopnost a politika vystavení ji zadržuje každému strojovému povrchu; čtecí polovina — changelog, zpráva o verzi a analýza — je schopnost, a je tedy na všech.

Chování při selhání

release::version::diagnose v modulu release je to, co odmítne druhé tvrzení. Hlásí version-stated-by-hand (chybu) pro nosič tvaru verze psaný ručně v bin/, lib/, scripts/ nebo share/ mimo generovaný artefakt — přiřazení do jména končícího na version (shell, TOML, JavaScript nebo Python), člen version: nebo "version":, nebo majordomus X.Y.Z produktu; projection-stale (varování — odmítnutí patří generate --check), když share/version.txt zaostává za manifestem nebo chybí; a writers-disagree (chybu), když předbíhá manifest nebo s ním nesouvisí. release analyze je nese na každém povrchu a release version je vypíše a skončí s 10. Kontrola version-authored-once spouští bin/majordomus-cli release version při každém plánu.

Kontrola release-check (scripts/ci/release-check) selže, exit 10, když:

• (1) manifest, který jmenuje zapisovač crate, není ten, který čte scripts/release-version;
• (2) bin/majordomus version nevypisuje, co manifest deklaruje (scripts/release-version --check);
• (2b) lock zaznamenává pro tento crate jinou verzi, než deklaruje manifest;
• (3) changelog je psán v kořeni repozitáře nebo pod docs/ mimo docs/generated/;
• (4) verze, kterou strom deklaruje, je za nejnovějším releasem, který vrstva zaznamenává;
• (5) publikovaný tag nemá ve vrstvě záznam o release.

majordomus generate --check je to, co dokazuje, že napsaný changelog a share/version.txt stále odpovídají tomu, co by z tohoto stromu vygeneroval generátor.

Ověření

scripts/ci/release-check                    # the gate
bin/majordomus-cli release version          # the version-authored-once gate
scripts/release-version --check             # the tool prints the authority
bash test/run.sh 484_the_version_is_authored_once 103_release_projection
majordomus release                          # the changelog, composed
majordomus release bump --dry-run           # what the one writer would write
majordomus generate --check                 # the written forms against the tree

test/cases/484_the_version_is_authored_once.sh prokazuje polovinu o verzi, každá sekce nejprve ukázána, že selhává proti stromu před verzí 2: nástroj neuvádí žádnou verzi, vypíše autoritu, protože čte vlastní projekci, ručně upravená projekce je odmítnuta, zapisovač zapíše jeden řádek manifestu a vlastní záznam zámku a verze zapsaná ručně v lib/ je odmítnuta. test/cases/103_release_projection.sh prokazuje polovinu o changelogu a zprávu, zapisovač a kontrolu proti repozitáři se skutečnou historií. apps/majordomus-cli/src/release/ nese jednotkovou polovinu.