HTTP API: release

Výjimka, kterou rozhodnutí uplatnilo, podle třídy.

use majordomus_cli::release::landing::AppliedExemption;
let e = AppliedExemption { id: "plan-records".into(), reason: "plan records".into() };
assert_eq!(e.id, "plan-records");

Co přistání přiděluje a proč, krok za krokem.

use majordomus_cli::release::compat::Impact;
use majordomus_cli::release::landing::{decide, LandingDecision, ReleasePolicy, DECISION_SCHEMA};
use majordomus_cli::release::version::Version;
let d: LandingDecision = decide(Version::parse("1.2.3").unwrap(), Impact::None, &ReleasePolicy::default(), &[]);
assert_eq!(d.schema, DECISION_SCHEMA);
assert_eq!(d.next_version, "1.2.3", "nothing moved and nothing is owed");

Zda executor integrace alokuje verzi, když přistává pull request.

use majordomus_cli::release::landing::Allocation;
// a policy that says nothing changes nothing: a pull request raises its own version
assert_eq!(Allocation::default(), Allocation::Off);
let a: Allocation = serde_json::from_str("\"landing\"").unwrap();
assert_eq!(a.as_str(), "landing");

Release, vůči kterému se tento strom měří, a jak byl nalezen.

use majordomus_cli::release::compat::Baseline;
let baseline = Baseline {
    version: "0.5.0".into(),
    reference: "v0.5.0".into(),
    read_at: "3a032c1e033b".into(),
    commit: "3a032c1e033b".into(),
    recorded: true,
    atoms: 300,
    fingerprint: "sha256:…".into(),
};
// `recorded` is the half that matters: a baseline taken from a tag alone is reported.
assert!(baseline.recorded);
assert_eq!(baseline.reference, "v0.5.0");

Jedna změna z jednoho commitu.

Zda změna přidala, odebrala nebo pozměnila část kontraktu.

use majordomus_cli::release::compat::Direction;
assert_eq!(Direction::Removed.sign(), '-');

Změny jednoho druhu, s nadpisem a pořadím, které rozhodují, kde se zobrazí.

Seskupení je v dokumentu, ne v každém rendereru. Bylo jen v rendereru Markdownu a web — který Rustovou funkci vidět nemůže — seskupoval abecedně, takže tentýž changelog se četl ve dvou pořadích podle toho, který povrch ho ukázal. Pořadí prezentace uvedené jednou a přenášené je jediný druh, který přežije projekci.

Celý changelog.

Jeden publikovaný artefakt, z vlastních důkazů záznamu vydání.

Co o sobě říkaly předměty commitů od základní linie.

Důkaz, nikdy autorita. Je zde, aby člověk viděl lidský popis a změřený vedle sebe a aby VersionPlan::understated mohlo říct, kdy se oba rozcházejí — což je případ, který má celý tento subsystém zachytit.

use majordomus_cli::release::compat::{CommitEvidence, Impact};
let commits = CommitEvidence {
    commits: 24,
    implied: Impact::Patch,
    breaking: Vec::new(),
};
// The contract moved by a minor and the subjects claim a patch: the plan reports that
// disagreement rather than deferring to the words.
assert!(commits.implied < Impact::Minor);

Jedno rozhodnutí, tak jak ho uvádí vlastní objekt ADR vrstvy.

Něco o stavu release, co by měl člověk vědět, ať je verdikt jakýkoli.

use majordomus_cli::release::compat::{Diagnostic, Severity};
let d = Diagnostic {
    id: "tag-without-record".into(),
    severity: Severity::Warning,
    message: "v0.1.0 is tagged and the layer holds no release record for it".into(),
};
assert_eq!(d.severity, Severity::Warning, "a warning states the plan still stands");

Jak moc změna hýbe kontraktem.

Uspořádané tak, aby „deklarovaný bump pokrývá požadované“ bylo porovnáním, a ne tabulkou:

use majordomus_cli::release::compat::Impact;
assert!(Impact::Major > Impact::Minor);
assert!(Impact::Minor > Impact::Patch);
assert!(Impact::Patch > Impact::None);

Politika kompatibility, pojmenovaná a verzovaná.

use majordomus_cli::release::compat::{Impact, Policy, POLICY_SCHEMA};
use majordomus_cli::release::version::Version;
let policy = Policy::for_version(Version::parse("0.5.0").unwrap());
assert_eq!(policy.schema, POLICY_SCHEMA, "a verdict carries the rules it was reached under");
assert_eq!(policy.required_of(Impact::Major), Impact::Minor);

Jak tento projekt mění změřený dopad na verzi, kterou dluží.

Sémantické verzování dává 0.y.z plošnou výjimku — „cokoli se SMÍ kdykoli změnit“ — a Elm tuto výjimku odmítá tím, že každý balíček začíná na 1.0.0, protože pravidlo s únikovým východem je pravidlo o tom, kdy použít východ. Tento repozitář je 0.x a nezasloužil si 1.0.0, takže není k dispozici ani jedna odpověď: požadovat major by znamenalo požadovat 1.0.0 za jedno odstranění a udělit výjimku by dovolilo vydat breaking změnu jako patch.

Takže pod 1.0.0 je spodní mez minor. Jakýkoli pohyb povrchu, zaniklý či nový, je přinejmenším minor release; jen nezměněný povrch nedluží nic. To je nejsilnější signál, který 0.x má, a odstranění se stále jmenuje jako zpětně nekompatibilní bez ohledu na verdikt, takže se důkazy potichu nestanou minorem spolu s číslem.

V 1.0.0 posun končí: Mode::Semver je běžné pravidlo a přechod je jeden řádek Policy::required_of.

use majordomus_cli::release::compat::{Mode, Policy};
use majordomus_cli::release::version::Version;
assert_eq!(Policy::for_version(Version::parse("0.9.0").unwrap()).mode, Mode::Pre1_0Strict);
assert_eq!(Policy::for_version(Version::parse("1.0.0").unwrap()).mode, Mode::Semver);

Která schopnost odpověděla tímto dokumentem a kde je tato schopnost promítnuta.

Dokument nese vlastní provenienci, aby čtenář — člověk na webu, klient přes MCP — našel stejnou hodnotu jinde, aniž by něco muselo vyčíslovat trasy. Stránka, která by je vypsala, by je deklarovala podruhé, což je selhání, které mají zachytit tvrzení site-check registry a cli; tohle zachytilo.

use majordomus_cli::release::model::ProducedBy;
let by = ProducedBy {
    capability: "release.changelog".into(),
    cli: Some("majordomus release changelog".into()),
    http: Some("/api/v1/changelog".into()),
    mcp_tool: None,
    mcp_resource: Some("majordomus://changelog".into()),
};
let json = serde_json::to_value(&by).unwrap();
assert_eq!(json["capability"], "release.changelog");
// a surface the capability is not projected on is absent, not null
assert!(json.get("mcp_tool").is_none());
assert_eq!(ProducedBy::default().capability, "");

Záznam vrstvy, který commit jmenuje ve vlastním textu.

Odvozeno, nikdy neuvedeno vedle commitu: id úkolu nebo id milníku ve předmětu či těle je odkaz a vrstva už objekt, na který odkazuje, drží. Odkaz na něco, co vrstva nemá, se nepřenáší — odkaz na neexistující záznam je horší než žádný odkaz, protože čtenář to pozná, až když ho následuje.

use majordomus_cli::release::model::Reference;
let r = Reference {
    kind: "issue".into(),
    id: "I1305".into(),
    title: "An observed contract has a fingerprint".into(),
    route: Some("/plan/i1305/".into()),
};
let json = serde_json::to_value(&r).unwrap();
assert_eq!(json["id"], "I1305");
assert_eq!(json["route"], "/plan/i1305/");
// a reference the site has no page for carries no route rather than an invented one
let bare = Reference { route: None, ..r };
assert!(serde_json::to_value(&bare).unwrap().get("route").is_none());

Changelog jedné verze.

Jak moc diagnostika záleží.

Chyba říká, že samotnému plánu nelze věřit, a blokuje verdikt; varování říká, že se stavem releasu je něco špatně, a verdikt přesto platí; poznámka říká něco pravdivého a ne špatného, aby varování znamenala to, co říkají.

use majordomus_cli::release::compat::Severity;
assert_ne!(Severity::Error, Severity::Warning);
assert_ne!(Severity::Warning, Severity::Note);

Zda strom smí přistát nebo být vydán tak, jak je.

use majordomus_cli::release::compat::Status;
assert_ne!(Status::Ok, Status::Blocked);

Jeden pohyb veřejného kontraktu s důvodem, proč se počítá tak, jak se počítá.

use majordomus_cli::release::compat::{Direction, Impact, SurfaceChange, SurfaceKind};
let change = SurfaceChange {
    impact: Impact::Major,
    direction: Direction::Removed,
    surface: SurfaceKind::Http,
    capability: "alpha.list".into(),
    id: "GET /api/v1/alpha".into(),
    detail: "the capability survives; this way of reaching it does not".into(),
};
assert_eq!(change.to_string(), "- route GET /api/v1/alpha");

Ve které projekci kontraktu je změna.

Ne kde to bylo nalezeno — vše zde se nachází v registru — ale jaký slib to je, aby čtenář viděl „trasa zmizela“, ne ukazatel JSON.

use majordomus_cli::release::compat::SurfaceKind;
assert_eq!(SurfaceKind::Http.as_str(), "route");

Kdo odpověděl na next reportu o verzi: veřejná smlouva, smlouva s commity — nebo nikdo, protože smlouvu nešlo změřit.

ADR 0051 činí smlouvu autoritou a degraduje konvenční commity na důkaz, takže DecidedBy::Contract je běžná odpověď. Neměřitelná smlouva se odmítne, ne hádá: DecidedBy::Undecided nechá next chybět a nese důvod a odvození z commitů zůstává tím, čím vždy je, důkazem — nikdy odpovědí na jeho místě.

use majordomus_cli::release::model::DecidedBy;
assert_eq!(serde_json::to_value(DecidedBy::Contract).unwrap(), "contract");
assert_eq!(DecidedBy::Undecided.as_str(), "undecided");
assert_eq!(DecidedBy::default(), DecidedBy::Undecided);

Celá odpověď: co se pohnulo, co to vyžaduje a co strom deklaruje.

Jedna hodnota, kterou vykresluje každý povrch — příkazový řádek, /api/v1/release/analysis, nástroj MCP, panel Cockpitu, vygenerovaný dokument i kontrola CI. Nikde neexistuje druhý výpočet, což je vlastnost, díky níž číslo něco znamená.

use majordomus_cli::release::compat::{Status, VersionPlan};
#### use majordomus_cli::release::compat::{Baseline, CommitEvidence, Impact, Policy};
#### use majordomus_cli::release::version::Version;
let plan = VersionPlan {
    policy: Policy::for_version(Version::parse("0.5.0").unwrap()),
    baseline: Baseline {
        version: "0.5.0".into(), reference: "v0.5.0".into(), read_at: "3a032c1e".into(),
        commit: "3a032c1e".into(), recorded: true, atoms: 300, fingerprint: "sha256:a".into(),
    },
    declared_version: "0.5.0".into(),
    tool_version: "0.5.0".into(),
    writers_agree: true,
    atoms: 333,
    fingerprint: "sha256:b".into(),
    implied: Impact::Minor,
    required: Impact::Minor,
    declared: Impact::None,
    required_version: "0.6.0".into(),
    status: Status::Blocked,
    breaking: false,
    changes: Vec::new(),
    commits: CommitEvidence { commits: 24, implied: Impact::Patch, breaking: Vec::new() },
    understated: true,
    diagnostics: Vec::new(),
};
// The contract requires a minor and the version declares none: this tree may not land.
assert_eq!(plan.status, Status::Blocked);
assert!(plan.declared < plan.required);
assert!(plan.understated, "the commit subjects claim less than the contract did");

Jaká je verze, čím se podle veřejného kontraktu má stát a co o sobě říkají commity od posledního release.

next je odpověď smlouvy (ADR 0051): required_version analýzy, nebo nejmenší release nad posledním, když je tento požadavek samotným posledním release. Odvození z commitů je důkaz — bump a commits_imply — a nikdy ne odpověď: když smlouvu nelze změřit, next chybí, decided_by je undecided a contract_unreadable říká proč. Výběr je crate::release::version::select, tedy jedna funkce, z níž release bump bere také svůj výchozí cíl.