pub const STATE_VERSION: u32 = 12;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.
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.