pub const STATE_VERSION: u32 = 24;Expand description
The version of the state document this build writes.
A file-backed state outlives the process that wrote it and is read by the next
one, which makes it a stored contract like onevcs’s own registry document —
and like that document, the version a document declares decides what is done
with it rather than being guessed at. STATE_VERSION is the shape the goldens in
tests/golden/ hold, and those goldens are compared byte for byte, so a change
to the document cannot reach a consumer without the diff saying so.
2 was what both sides learned when publishing and closing a session came
through the interface: VcsState::policy, VcsState::closed_sessions,
VcsState::publications, and HostState::titles. 3 is
HostState::bodies, the body a change request was opened with. 4 is the two
fields a Recoverable gained inside VcsState::preserved — the live session
holding a branch, and the lines it would land when it removes more than it adds.
5 is one more of those: whether the branch’s work reached its base, and what
says so. 6 is the two a Check gained inside HostState::checks — the
commit the host attached that check to, and where the check is on the host. 7
is the two a draft change request needs — HostState::drafts, the reason each
change request was opened as a draft with, and HostState::made_ready, the
ready_for_review calls it took. 8 is the two an Identity inside
VcsState::identities lost — workflow and repo_type, the registry’s
inferences from whether an origin had a host, which every decision they made now
takes from the resolved publication policy instead. 9 is the draft reason inside
HostState::drafts becoming one of two kinds and saying which — kind is
awaiting-release or held — and HostState::described, the descriptions a
host was handed for a change request after it was opened. 10 is the failure
vocabulary a publication’s outcome inside VcsState::publications may name
widening by one kind, host-prerequisite — no field moved, but a document naming
it is one a version 9 build cannot read, and the version is how it says so. 11 is
one more field a Recoverable gained inside VcsState::preserved, the same way
4 and 5 were: where onevcs preserve put that branch on its identity’s origin,
and the commit the origin carries it at. 12 is the labels a session is opened
with — VcsState::session_labels, keyed by token the way its identity is — and
the two fields a Recoverable gained inside VcsState::preserved to carry them:
the session that answers for the row, and that session’s labels. 13 is one more
field a Recoverable gained there: the branch’s retirement classification — whether
it provably holds nothing beyond its base, was superseded by a retry that landed, or
is kept, and the evidence for it. No provider here classifies a row, so a row this
crate writes carries none; a scenario may seed one. 14 is the draft lifecycle:
HostState::awaiting_checks, the change requests opened as a draft while their
required checks run, HostState::checks_after_lift, the checks a host registers
only once a change is lifted, and HostState::required_checks, what the host
says a merge into a base requires — beside VcsState::approvals and
VcsState::drafts, the two policy fields a provider’s publication now routes
the lifecycle on. A publication outcome inside VcsState::publications may also
be change-review-draft. 15 is the field a Session gained inside
VcsState::sessions: conflict, the merge a continued branch’s session opened
over and left in progress. No provider here merges a base into a branch, so a
session this crate opens carries none; a scenario may seed one. 16 is the failure
vocabulary a publication’s outcome inside VcsState::publications may name
widening by one kind, cancelled, the way 10 widened it — no field moved, but a
document naming it is one a version 15 build cannot read. No provider here waits on
anything, so a publication this crate runs is never cancelled; a scenario may seed
one. 17 is the field a Retirement gained inside a row of
VcsState::preserved: cause, the read that failed for a branch kept as
unknown, which every retirement writes — null for every other reason. No
provider here classifies a branch, so a row this crate writes carries none; a
scenario may seed one. 18 is what the record of a gate run and of a landing needs
from a host: the field a Check gained inside HostState::checks —
completed_at, when the host says that run completed — and
HostState::merge_times, when each merge this host performed reached its base.
Every change to the document is versioned, an added field included. A field
that only ever appears when it holds something is compatible — that is what
OLDEST_READABLE_VERSION is for — but compatible is not the same as
unremarkable: the version is how a consumer’s checked-in scenario says which
shape it was written against, and a document that gained a field without saying
so leaves nothing able to tell “this build wrote no body” from “this document
predates bodies”. The two answers differ for exactly the journey this crate
exists to support.
19 adds the recovery branch tip; older rows default it to None. 20 is the
review feedback a host holds: HostState::review_comments, each change
request’s comments of every kind, HostState::replies, every reply this host
posted, and HostState::review_charges, what it charges a read. 21 is what a
stack of drafts needs from a host while people merge some of them on it:
HostState::closed, the change requests closed without merging,
HostState::deleted_branches, the branches gone from the origin,
HostState::head_checks, each required check’s state per head commit, and
HostState::ledger, every call the host answered with what GitHub charges for it.
22 is what an elapsed watch arms: HostState::up_to_date_required,
HostState::allow_auto_merge and HostState::armed, and a failed publication’s
armed merge. 23 is what a draft’s watch reads per poll:
HostState::check_readings and HostState::check_readings_after_lift, the
checks each reading of a change request reports in turn on each side of its lift,
and HostState::head_activity, what the host answers in turn about the work
still running on its head. 24 is a ledger that may name merged_head, the
question a retirement asks a host before it calls a branch merged.