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 session's check of a check-in it was given: tag
ci, valuefail: 2 tests failed (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 program that
checks the check-ins its session is given writes a ci verdict on each, as its
run's user, against its run.
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 user of the run it names sent it, and that run
has a started that counts (protocol v1, section 10):
anyone may write a run naming themselves its user, but only its node starts
it. A run named in a 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.
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 queue and activity, 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; 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).