tama contributions

Reports to Wisent's contribution ledger, in compute.wisent.com, the commits that reached a repository's remote with a standing attestation, so the people who write accepted code are credited for it.

#Invocation

tama contributions pending --repository <PATH> --ref <REF> [--since <REV>] [--ledger <URL>] [--json]
tama contributions report  --repository <PATH> --ref <REF> [--since <REV>] [--ledger <URL>] [--json]

• --repository — the checkout to read.
• --ref — the remote branch the commits reached, as this checkout last fetched it, such as origin/main.
• --since — leave out every commit that revision already holds.
• --ledger — the ledger's origin; without it, TAMA_CONTRIBUTION_LEDGER_URL.

#What counts

A commit is accepted code when it is reachable from --ref and its message or attestation note carries every claim of the commit standard and a harsh review with no finding, exactly as tama attestation check reads it. Each is one code.accepted contribution of its git author, whose email is the identity the ledger credits. Tama links no one: an author links that address to their Wisent account with Link my email for Tama on the Rewards page of compute.wisent.com, which takes the account's own verified address, so nobody can claim an address that is not theirs. Until then the ledger holds the author's events and credits nobody. The commit id is the event id, so reporting the same range again records nothing twice.

#Output

Both verbs ask the ledger once which of the events it already holds, so a report sends only the commits it lacks however long the range. pending prints one line per accepted commit — the commit, its author and its commit time, and with a ledger named whether the ledger holds it — or with --json the events themselves, each with held when a ledger is named. report prints, per commit it sent, <COMMIT> recorded: …, <COMMIT> refused: … with the ledger's own sentence, or <COMMIT> not answered: … with what the request met when no answer of the ledger came back, and the ids it already held; with --json, {"ledger", "events": [{"commit", "answer"} | {"commit", "refused"} | {"commit", "unanswered"}], "held"}. It exits 1 when the ledger refused or did not answer any commit.

#In Tama Desktop

The Contributions screen runs the same two operations as desktop requests contributions/pending and contributions/report, whose bodies carry the same fields as the flags (repository, ref, since, ledger) and whose answers are the documents --json prints. A report the ledger refused in part is answered whole, each refused commit carrying the ledger's sentence as refused, so the screen shows it on that commit's line, counts the refused apart from the recorded, and reads the pending list again. A report in which the ledger did not answer for some commit is a failure, the ledger did not answer for [<COMMIT>, …]; the report: <REPORT>, since nothing the ledger decided can be shown for those commits. Every other refusal is shown in Tama's words.

#What it reads

The bearer it presents as the reporter tama is the token field of the item playing tama-contribution-ledger, read with stado credentials get; the ledger's operator declares that bearer's SHA-256. The bearer and the event go to the HTTP client on its standard input, never on its command line.

#Refusals

Usage errors exit 2, before anything is read or sent:

• contributions: name a verb: tama contributions pending|report … — no verb.
• contributions: <word> is not a verb of tama contributions … — a verb other than pending or report, link among them.
• contributions: <word> is not an argument of tama contributions … — an argument the verb does not take.
• contributions: --ref names no value — and likewise for --repository, --since and --ledger: a flag at the end with nothing after it.
• contributions: --repository names the checkout: … and contributions: --ref names the remote branch the commits reached: … — the flag is missing.

Every other refusal exits 1. Naming the ledger:

• contributions: no contribution ledger is named; pass --ledger URL or set TAMA_CONTRIBUTION_LEDGER_URL — from report. A --ledger or TAMA_CONTRIBUTION_LEDGER_URL that is empty once the spaces around it and then the slashes at its end are taken off names no ledger; pending then lists the commits without asking one.
• contributions: TAMA_CONTRIBUTION_LEDGER_URL is not valid Unicode

Reading the checkout:

• contributions: git rev-list --reverse <REF> [^<REV>] in <CHECKOUT> failed: … — the reference or revision is not in the checkout, in git's words; … in <CHECKOUT>: … when git cannot be run.
• contributions: this Tama cannot name its own program: …, contributions: tama attestation check of <COMMIT>: … and contributions: tama attestation check of <COMMIT> answered no JSON (…): … — a commit's attestation could not be read.
• contributions: git names no author email or commit time for <COMMIT>: …

Reaching the ledger:

• contributions: stado credentials get --role tama-contribution-ledger --field token: … when Stado cannot be run, and … gave no bearer (<STATUS>): … when it reads no token.
• contributions: asking the ledger what it holds failed: …, followed by the ledger's own sentence, or by what the request met: POST <URL> refused: <ANSWER>, POST <URL> answered no JSON (…): <BODY>, POST <URL> failed (<STATUS>): …, cannot start /usr/bin/curl for POST <URL>: … or cannot hand /usr/bin/curl the request for POST <URL>: ….
• contributions: the ledger's answer names no held list: <ANSWER> — the ledger answered without the events it holds.
• contributions: the ledger refused some commits; each is named above — after a line <COMMIT> refused: … for each, in the ledger's own sentence (or POST <URL> refused: <ANSWER> when its refusal carries none).
• contributions: the ledger did not answer for <N> commit(s); each is named above — after a line <COMMIT> not answered: … for each, with one of the request sentences above; it takes the place of the refused summary when both happened.

The real test is tests/contributions/report.rs.