A verdict is a tag on a check-in that records a judgement of it: audited
for one made by a person or an agent, ci for a program's check. Runs of
protocol v1 write them, but a verdict needs no run: anyone
may write one.
Writing a verdict
Write it as a raw tag (Fossil's --raw), so it never becomes a name for the
check-in, and on that check-in alone, never propagating to its descendants. A
reader reads sym-audited and sym-ci tags as verdicts too, as older OCX
wrote them, each on the check-in it names alone. Its value
is pass: or fail:, then the reason on one line, then (against X),
where X names the objective it was judged against: a run's full hash, or the
path of a file that states the objective, such as PLAN.md, read as it stands
in the check-in judged. X is everything after the value's last (against,
up to its final ); a value not of this form is no verdict. Two examples:
- a reviewer's judgement: tag
audited, valuefail: the new command has no tests (against [PLAN.md](../PLAN.md)); - a build's check of the check-in it took, written by its node: tag
ci, valuefail: exited 1 (against RUNHASH).
Anyone may write an audited verdict, with OCX's audit tool or with
Fossil's own fossil tag add; it needs no run. But a verdict on your own
check-in never counts: the author of a check-in cannot pass it. A node writes
a ci verdict on the check-in a build took, as the node user, against the build's
run, when the run asks for it; CI of a branch is a session that sends a build
of each check-in it is given.
Reading verdicts
A verdict counts only if its sender
(Fossil, senders and nodes, section 3) neither sent the
check-in nor is the user named in it. An audited verdict counts only if a
user who holds check-in (i) when it is read sent it, and no node user: one
named as the node of a run that an admin or setup sent; capabilities are
taken when it is read, so a revoked reviewer's verdicts stop counting. A ci
verdict counts only if the node of the run it names sent it, that run has a
started that counts (protocol v1, section 10), and
the check-in is the one that started names: a build that holds no credential
is judged by its node, as its verdict asks (protocol v1, section 8),
never by a run's own program, which may run the change under test. A run named
in an audited verdict must be about the check-in: the check-in its
started names, or one on a branch in its checkins, by the check-in's
branch as Fossil's timeline shows it: the branch tag it carries, which a
branch's first check-in sets and the check-ins after it inherit. An X that is a hash in full is read as a run's, so a verdict against one that names no run counts for nothing.
Fossil shows only a tag's latest value on a check-in, but keeps every tag
change in its event table (type g). So a reader takes the tag changes from
there and counts, for each user who sent a verdict, that user's
latest for each tag and each objective (X), by the server's receipt order,
which a reader on a clone learns from receipt: the times written in tag
changes are their writers' clocks, and decide nothing.
Cancelling a tag (fossil tag cancel) writes no verdict, and leaves the
verdicts before it standing: nothing is retracted.
How to combine the verdicts that count is the reader's choice: any fail fails,
a majority, one named reviewer. OCX's unaudited, CI checks and
merge gates are all readers. A reader on the server counts by its receipts,
and a reader on a clone asks the server with OCX's receipt tool, as a node
does, or asks the server's own reader, as unaudited does; one that cannot ask counts by the user named in each tag change, and
says its count is unverified.
Why: Ax2 (always judged against a named objective), Demonstrability (attributed by receipts, and kept), Loose Coupling (a verdict needs no run, and any program may read one).