Zdůvodnění
project.land-and-publish už říká, že merge měnící veřejný kontrakt nese svou verzi, a říká to proto, že publikovaný web jednou uváděl verzi o tři vydání starší než kód. Co říct nedokázal, bylo která verze, protože zvýšení rozhodovala slova v commit zprávách: feat: znamenalo minor, fix: znamenalo patch a schopnost smazaná pod nadpisem refactor: neznamenala vůbec nic.
Číslo, které si člověk zvolí, je tvrzení, a tvrzení o kompatibilitě je druh, který nikdo nemůže ověřit čtením. Tento repozitář takové vydal: mezi v0.3.1 a 0.4.0 atom command scope classify opustil veřejný povrch a žádný release to neřekl.
To, co odešlo, bylo tvrzení, ne dispatch, a právě to udělalo mlčení drahým. repository.scope_classify deklaroval cli: ["scope", "classify"], aby jeho příkazový modul mohl najít vlastní id podle cesty; strom clap ten podpříkaz nikdy neměl, ani při v0.3.1, ani nyní, a majordomus scope classify <path> parsuje classify jako cestu k posouzení a odpoví out undeclared classify [absent] s exit 0. Generovaná reference, dokument OpenAPI i publikovaný web příkaz přesto inzerovaly, protože každé je projekcí registru — takže volající si ho tam přečetl, zadal a dostal věrohodnou špatnou odpověď místo odmítnutí. Smazání tvrzení bylo záměrné a správné (ADR 0027, project.commands-are-projections). Každá kontrola byla celou dobu zelená, protože do tohoto pravidla se žádná na tento povrch nedívala.
Správce balíčků Elm na to odpovídá odmítnutím přijmout číslo verze, které zvolil člověk: porovná veřejné API a spočítá velikost změny a balíček, jehož číslo je menší než jeho změna, nelze publikovat. Podstatou není diff, ale odmítnutí — verze má hodnotu jen tehdy, když nemůže být menší než pravda.
Tento repozitář to dokáže bez nového enginu, protože už při každém commitu commituje popis celé své veřejné plochy. Registr schopností je jedna deklarace, jejíž projekce jsou MCP, HTTP, OpenAPI a příkazová řádka (ADR 0002, ADR 0027), a docs/generated/registry.json je ve stromu při každém commitu a každém tagu. Plochu libovolných dvou refů lze proto porovnat, aniž by se kterýkoli z nich sestavoval.
Co verze 1 tohoto pravidla nechala otevřené
Verze 1 byla vynucována shellovým skriptem a z toho vyplynuly tři věci, které se ukázaly až při používání (ADR 0051).
Nebyla to jediná odpověď. majordomus release bump — jediný zapisovač, který číslo skutečně nastavuje — počítal vlastní úroveň z typů conventional commitů, takže repozitář měl měření a odhad odpovídající na tutéž otázku. Rozcházely se přesně u změny, která něco odebírá, a vyhrál odhad, protože zapisovač běží na vývojářově stroji a kontrola běžela až potom, pokud vůbec.
Běžela téměř nikdy. Kontrola byla deklarována v modelu CI a nevybrala ji žádná třída cest, takže byla plánována jen při plném běhu. Pull request, který přidal devět schopností a verzi nechal být, se na tuto otázku nikdy nedostal; origin/master přesně to nesl, když se tato verze psala.
Viděla jen jména. Porovnávala seřazené řádky, takže přidané povinné vstupní pole, odebrané výstupní pole, zúžený výčet nebo změněný typ — vše, co rozbije volajícího a co commitnutý registr popisuje celé — pro ni bylo neviditelné.
Požadované chování
Měří jeden stroj a nic jiného nerozhoduje. apps/majordomus-cli/src/release/compat.rs vypočte úroveň z veřejného povrchu (release/surface.rs) a každý povrch, který ukazuje verdikt o verzi, vykresluje tu jedinou hodnotu: příkazový řádek, GET /api/v1/release/analysis, nástroj MCP majordomus_release_analysis, Cockpit, generované dokumenty, kontrola CI i zapisovatel. Nikde neexistuje druhý výpočet.
Povrch je to, co může volající držet: identita a druh veřejné schopnosti, nástroj a zdroj MCP, na které odpovídá, metoda a cesta HTTP, ke kterým je vázána, cesta příkazové řádky, která ji dispatchuje, a obě její schémata. Ztráta kteréhokoli je zpětně nekompatibilní, i když schopnost přežije, protože volající, který drží to staré, je tak či tak rozbitý.
Mezi posledním releasem a stromem:
- atom, který zmizel, nebo kontrakt, který se pod volajícím zúžil, znamená změnu major,
- atom, který je nový, nebo kontrakt, který se rozšířil, implikuje minor,
- nezměněný povrch dluží žádné zvýšení verze: posuzuje se to nad každým stromem, ne jen nad releasem, a většina commitů leží za hranicí. Kontrola, která by zvýšení po každém z nich požadovala, by byla věcí, kterou je třeba obejít do jednoho dne.
Schémata se porovnávají jako kontrakty, v obou směrech. Vstup je to, co volající posílá, takže přijímat více je kompatibilní a vyžadovat více je breaking; výstup je to, co volající dostává, takže slíbit více je kompatibilní a slíbit méně je breaking. Tatáž úprava je v jednom případě minor a v druhém major. Próza — popisy, názvy, příklady — se nejdřív normalizuje pryč, takže přeformulovaný dokumentační komentář není release. Mutace kontraktu, kterou komparátor nemodeluje, se počítá jako breaking a říká to: falešný major je argument, který může někdo vyhrát, falešný patch je volající, který to zjistí tím, že mu věci přestanou fungovat.
Tento strom se čte živě; release se čte ze svého commitu. Aktuální povrch pochází z registru v procesu, takže zastaralá commitnutá projekce nemůže způsobit, že porovnání popíše starší strom. Vydaný ref takovou možnost nemá, proto se použije registr commitnutý v něm — a ref, který žádný nenese, odmítne, protože prázdný základ hlásí každou schopnost jako novou a prázdná hlava hlásí každou jako odstraněnou.
Základem je nejnovější release, který vrstva eviduje, ne nejnovější věc, která vypadá jako tag; tag bez záznamu i záznam bez tagu se hlásí.
Conventional commits jsou důkaz. Zůstávají prózou changelogu a lidským popisem změny, nesou se v plánu vedle verdiktu, a když okno klasifikují jako menší, než o kolik se pohnul kontrakt, odpověď to řekne, místo aby se jim podřídila.
Jeden zapisovač a žádné přepsání pod podlahou. majordomus release bump čte plán a uplatní ho — plan → validate → apply(plan), nikdy druhý výpočet. --level a --exact mohou jmenovat verzi nad naměřeným minimem, hlášenou s její proveniencí, a pod ním jsou odmítnuty bez zápisu. Verze nikdy neklesá.
Pod 1.0.0 je požadovaným zvýšením minor při jakékoli změně povrchu, ať zanikl nebo přibyl. Sémantické verzování uděluje 0.y.z plošnou výjimku a Elm tuto výjimku odmítá tím, že každý balíček začíná na 1.0.0; tento projekt je 0.x a nezasloužil si ani jednu odpověď, takže bere nejsilnější signál, který 0.x má, místo aby kvůli jednomu odstranění požadoval 1.0.0. Když major dosáhne 1, posun končí a odvozené zvýšení je zvýšením požadovaným.
Je to typovaná, verzovaná politika — majordomus/version-policy/v1, s režimem určeným jen verzí základního stavu — nesená do každého verdiktu, aby rozhodnutí zaznamenané dnes zůstalo vysvětlitelné, až se politika změní. Není to zvláštní případ uvnitř skriptu.
Odebrání se pojmenuje, ať je verdikt jakýkoli. Pod 1.0.0 release neodmítne a stále se uvádí jako zásadní změna: volající, který držel, co zmizelo, by to jinak zjistil tím, že se mu to rozbije.
Kde se to uvádí, určuje to, co to udrží. Changelog je odvozený a záznam release je důkaz zapsaný pipeline, takže ani jeden není autorský — jediný autorský vstup, který o změně čtou, je zpráva commitu. Odstranění se proto jmenuje v předmětu commitu uvnitř release, který je nese, označeném type(scope)!: nebo trailerem BREAKING CHANGE:, který release/commits.rs čte a release/changelog.rs vykresluje s úvodním **BREAKING**. majordomus release changelog jej ukáže pod ## Unreleased hned; docs/generated/changelog.* jej ukáže, až se verze vydá, protože commitnutý artefakt nese jen publikované release. Mechanismus a pole, které záznam release nemá, jsou v docs/RELEASE.md pod Kde je odstranění zapsáno.
Chování při selhání
scripts/ci/version-matches-surface, registrovaná jako kontrola version-surface, je adaptér nad majordomus release analyze a nemá vlastní sémantiku. Skončí s kódem 10 a jmenuje každý pohyb a důvod, proč se počítá tak, jak se počítá, a s kódem 12, když analýzu nelze provést vůbec — není s čím porovnávat release, registr základní hodnoty není commitnutý, klon je mělký. Tyto dva stavy se záměrně drží odděleně: „nedokázal jsem to určit“ a „odpověď je ne“ jsou různá fakta a kontrola, která první hlásí jako druhé, oslepla, aniž by to řekla.
Kontrola se vybírá podle tříd cest rust, rust-generated a distribution, takže změna, která může pohnout veřejným kontraktem, ji spustí před přistáním; běží v úloze rust, která má spustitelný soubor a celou historii, kterou potřebuje.
majordomus release bump odmítne, aniž by cokoli zapsal, když je požadovaná verze pod naměřenou spodní hranicí, pod tím, co strom už deklaruje, nebo když samotný plán nese chybovou diagnostiku.
Odmítnutí není žádost o nafouknutí čísla: odebrání, které bylo chybou, se vrátí, a to, které bylo záměrné, se vydá jako to, čím je.
Ověření
apps/majordomus-cli/src/release/compat.rs nese matici kompatibility: každý řádek výše, oba režimy politiky, porovnání schémat v obou směrech a invarianty determinismu — přeuspořádání není změna, povrch porovnaný sám se sebou je prázdný a zpráva je funkcí obou povrchů, ne pořadí, v jakém je registr vyjmenoval. release/surface.rs nese otisk, normalizaci a každý způsob, jak může být baseline nečitelná.
test/cases/112_version_matches_surface.sh je behaviorální polovina, v jednorázovém repozitáři se skutečnou historií a skutečnými publikovanými release: aditivní změna odmítnutá a poté opravená zapisovačem, nedostřelující přepis odmítnutý s nedotčeným manifestem, přestřelující povolený a nahlášený jako přepis, nezměněná smlouva, která nic nedluží, odstranění označené jako breaking, nečitelná základní hodnota odmítnutá jako nečitelná, a ne jako prázdný diff, tag, který nikdo nezaznamenal, nahlášený, a — tvrzení, které drží adaptér adaptérem — kontrola a engine končící stejným kódem na stejném stromu.