Contributing¶
What this repository holds in common with the others of the organization — the toolchain, the lint gate, the tool tables behind it, the workflow set and the branch rules — is stated once in the btclib-org repository standard, each rule with the alternative it was decided against. It binds this repository, so a change departing from it is a divergence, and one filed as an issue in that repository rather than here: a difference between two repositories belongs to neither of them.
This file is the same in every repository of the organization up to its last section. What is true of one tree only — the commands that build its environment, the gates it runs, which of its workflows decide a merge — is under that heading, and the comparison stops there.
How the organization decides, and who holds which role, is
GOVERNANCE.md; what it intends to do, and what it
deliberately does not, is ROADMAP.md. Both are the
organization’s, one copy each beside the standard.
The issue tracker¶
Where an issue is filed, and what an alignment finding has to name, is the standard’s What this repository is: an issue spanning repositories, or whose subject is the standard, goes to btclib-org/.github, and one about this tree alone stays here.
A finding noticed while doing something else goes where REVIEWING.md’s
What is filed, and what is not says, for an author as much as for a
reviewer: a pull request answering two questions cannot be accepted for
either.
An issue labelled good first issue is one set aside for a first
contribution: small and self-contained.
One search lists the open ones across the organization, so
a newcomer need not know in advance which repository to look in.
Documentation and comments¶
Section 9 of the standard is the prose style beyond Write plainly below, and it governs the prose this tree ships — comments, docstrings and markdown. It is not restated here: a second wording is the one that goes stale, which is that section’s own One fact in one place.
A commit message is prose this tree ships too, though section 9 does not
say so: the only merge method the rule accepts puts it on main
as the landing commit’s body, so what is written in one is read there
long after the branch is gone.
Working with an LLM¶
Development here is LLM-based. Most issues, code and reviews are written by agentic sessions that the maintainer directs and reads. Humans are welcome, as long as they are comfortable working that way.
A contribution is yours, whoever wrote it. Read every line before you open the pull request, understand it, and be ready to answer a review without the model. Text or code you have not read, or cannot explain, is closed without review.
Write plainly, in the tree and on the forge: the point first, plain
words, one fact per sentence. On the forge, the title and the first
sentence carry the point; a body is at most two short paragraphs before
any code block or template section; a comment is about 200 words, and
never more than 250, with no list and no heading; a review’s summary
takes the shape REVIEWING.md’s The verdict gives it.
Pull requests¶
What main accepts, and what it refuses to everyone, is section 11 of
the standard. Run the gates locally before opening anything —
the last section of this file says which they are — because CI runs
exactly them, so a red run there is a local run that was not done.
Every commit of a pull request carries a Signed-off-by: trailer
naming its author, which certifies the Developer Certificate of
Origin. git commit -s adds it, and git rebase --signoff <base>
adds it to commits already made. The Sign-off check is required, so a
pull request whose commits lack the trailer cannot merge; its failure
prints the command that adds it. The standard’s Signatures
says why a signature does not replace it, and which commits the
Sign-off job skips.
What a pull request’s title and description have to say about the issues it closes, and why a manual link in the Development panel is a trap neither of them shows, is the standard’s What a pull request says it is. Read it before opening one; it is the rule most often found broken after the fact.
Before it is opened, the branch’s own commit subjects and bodies are read against that same rule. The description does not exist yet to disagree with them, and the standard has the command that scans the branch’s own commit text for a verb in front of a reference.
The two spellings are named here as well as there, against section 9’s
One fact in one place, the paragraph above naming the section
and not the forms, which are the half a citation is got wrong in:
(closes #N) cites an issue the change closes, wherever the citation
sits — the title, the commit subject where Merge method makes
that the thing that lands — and (issue #N)
cites, in those same places, an issue the change advances and does not
close. One token holds one meaning whichever file it sits in, so the
pair is chosen by what is true of the change rather than by which file
is being written, and a tree’s own landed subjects are not what to copy
it from: nothing already landed is rewritten, so what a repository wrote
before the rule stays where it is.
REVIEWING.md is the standard a review is written against, and is this
file’s other half. Read before opening a pull request, it is what the
pull request will be answered against.
A pull request adds no entry to CHANGELOG.md or RELEASE_NOTES.md, a
release’s own pull request excepted (section 9, section 12).
One subject, opened as soon as it is written¶
A pull request answers one question. Issues that share a subject are one pull request, closing each of them; issues that do not are one pull request each, however small either of them is.
It is opened the moment it is written and verified — not held for the previous one to be reviewed or to land, and not batched with the next. A batch arrives as one reviewing job with several subjects, which is the shape that costs the most to read; a finished pull request held back is review that could have started and did not.
Working this way stacks branches, which is fine and costs one rule: a child whose base was amended is moved with the old base named,
git rebase --onto <new-base> <old-base-sha> <child>
because a plain rebase replays the base’s old commit inside the child,
and the forge then shows the base’s old text as additions with nothing
red anywhere. Read the child’s diff afterwards rather than trusting the
rebase, and retarget each child onto main as its parent lands.
The review¶
A review is given promptly and on local evidence. It does not wait for CI, does not report a check as a finding, and does not discuss a run at all: whether CI is green is the author’s business, once, at landing time.
The exchange is anchored to a sha rather than to a branch, a branch being free to move under a review:
the author hands off by naming the sha pushed and the evidence run against it, then leaves that head alone;
the reviewer answers with findings — where, what is wrong, how they know it, and whether each is blocking;
the author accepts what is reasonable, declines the rest with a reason in the thread, pushes the answer without waiting for CI, and resolves each thread once answered;
the reviewer reopens a thread whose finding is still blocking, and re-reviews the delta rather than the branch.
What ends the loop is the ack of record, and the author does not
supply their own. A reading that says what it found and delivers no
verdict is a review too and ends nothing; the standard’s Review
has which is which, and REVIEWING.md has how each is written. A
disagreement that survives a second exchange goes to the maintainer
instead of into a third round.
The ack of record is not the approval Landing it asks for: it is a bot’s review of type COMMENT (the standard’s Review says whose).
Landing it¶
CI is read once, and this is where: on the head that lands. main does
not ask that head to be up to date with it, and section 11
says why. So a branch is rebased only where it conflicts with main. A
rebase that moved nothing but the base leaves the ack standing; one that
resolved a conflict does not, that resolution being a change no reviewer
has seen.
When main’s CI is red after a merge, its repair takes priority over
every other pull request, because until it lands main’s runs cannot
tell a new failure from the one already there. A pull request armed with
--auto (below) stays armed, and others keep landing meanwhile. Holding
every landing for a repair costs more than the break it guards against,
so the risk of landing on a red main is accepted
(btclib-org/.github#1777).
A pull request whose required check is red only because main was red
is closed and reopened once the repair lands (gh pr close <n>, then
gh pr reopen <n>). GitHub then runs its checks on a fresh merge with
the repaired main, where a re-run would test the old merge commit. No
push is made, so its approvals and its ack of record stand. --auto,
where closing dropped it, is armed again once the checks are green. The
reopen also runs the review bot again, and changes that review requests
are answered like any other review’s.
Then squash, the only method the rule accepts.
It lands once somebody other than its author has approved that
head, through gh pr merge pinned to it:
gh pr merge <n> --squash --match-head-commit <the head the checks ran on>
With --auto added, GitHub runs the same merge once the approval and
the checks are in.
Where the repository has a bypass, the maintainer may land without
that approval, through it: GOVERNANCE.md’s How a
decision is made says which repositories.
--admin turns off gh’s own refusal, and GitHub applies
the bypass to the merge. enforce_admins is off, so it waits for no
required check either:
gh pr merge <n> --squash --admin \
--match-head-commit <the head the checks ran on>
Without --admin, gh pr merge refuses a head with no approval, saying
it is not mergeable: the base branch policy prohibits the merge.
The pin is not optional, in either command. Reading the ack and
merging are two calls, and the head is free to move between them — the
push that would move it comes out of the same round the verdict does.
Unpinned, the command takes whatever sits at the head when it runs;
pinned, it refuses a head that has moved, and a round lost that way is
cheaper than a tree nobody has read reaching main.
The review above anchors the exchange to a sha and section 11
has an ack name one: the pin is that rule reaching the call that
performs the landing.
Verify what landed rather than trusting the answer, the signature the standard asks for being a valid one rather than a particular signer’s:
gh api repos/{owner}/{repo}/commits/main \
--jq '.commit.verification | {verified, reason}'
What it closed is read again here too, from the landed sha rather than from the pull request: the standard’s What a pull request says it is has the second read, and why the first alone does not reach a squash subject composed after it runs.
The forge deletes the head branch itself, per the setting section 11
names. What is still yours is bringing every checkout sitting on main
up to date,
that being where the next session starts from and a stale one being where
a branch gets built on a base that has moved. REPOSITORY.md carries the
settings and why they are what they are.
Worktrees¶
Run git fetch origin in the primary checkout, then check that
git status --porcelain is empty and git branch --show-current is
main. Run git pull --ff-only only when both checks pass, then verify
git rev-parse HEAD origin/main prints the same sha twice. Create a separate
worktree for each task with
git worktree add <path> origin/main -b <branch>. After committing,
remove it with git worktree remove <path>. If initialized submodules
make that fail,
check for uncommitted, untracked, and ignored files in the worktree and
its initialized submodules. Preserve anything needed before retrying with
git worktree remove --force <path>; it can delete those files. Keep the
primary checkout clean and on main; do not
switch branches or stash there. Hooks can fix files in place, and the local
main and refs/stash are shared by all worktrees.
This repository in particular¶
Everything above is the same file in every repository of the organization; everything below is this one’s, and the comparison stops at this heading.
[](https://calver.org/)
To get an overview of the project, read the README and the
docstring at the top of src/bitcoin_core_rpc/__init__.py, which is where the
design and the reason behind every refusal are written down.
What a method does is Bitcoin Core’s, not this client’s: an RpcError
carrying a code is usually a question for the method’s documentation
rather than an issue here.
The one constraint¶
This package carries nothing but the standard library behind it, and
it stays that way: errors.py, chains.py, transport.py and
client.py, each importing only the standard library and each other in
the order errors < chains < transport < client.
tests/census_test.py is what fails when a module takes a dependency
outside that or imports one later than itself in that order — it reads
the imports of every source file with ast rather than trusting what
ran.
__all__ is the public surface. A name is public because that list says
so, not because it happens to lack a leading underscore.
The environment and the gates¶
uv is the only tool that must be installed; it fetches interpreters,
linters and packaging tools itself. uv sync creates the environment.
uv sync
No test here reaches the network and none needs a node: every client in it is
built with a transport= that answers from bytes committed under
tests/_data. What a live node answers is a separate question, asked by
integration-bitcoind.yml and by the command under
A live node below.
The gate is the suite, the hooks and the documentation build:
uv run pytest
uv run pre-commit run --all-files
uv run --locked --no-default-groups --group docs \
sphinx-build -n -W -b html docs/source docs/build/html
--cov is in addopts, so the bare pytest above is the coverage gate
and fail_under = 100.0 is what it answers against; pyproject.toml
says why the flag sits there rather than in the workflow that used to
carry it. A selective run is reported and not gated —
uv run pytest tests/transport_test.py prints a coverage of the whole
tree and passes — and tests/conftest.py’s pytest_configure is what
makes that difference.
The documentation build is the one to remember, because no hook reads
reStructuredText: a docstring docutils cannot parse fails it with every
hook green — a name ending in an underscore is a reference to a link
target (mult_, and the fix is those very backticks). That build is not
the whole of the docs job: the steps after it read the pages it wrote,
and Reproducing what CI runs below carries them with it in one block.
Check exit codes, not filtered output. pre-commit run ... | grep -v Passed hides a failure, and grep finding nothing exits 1, which is not
the gate’s answer to anything.
The lint gate is not installed as a git hook. pre-commit install
writes into the common git directory, which every worktree of this
repository shares: git -C <worktree> rev-parse --git-path hooks answers
with the primary checkout’s .git/hooks from every one of them. So one
session installing it installs it for every other. Run the gate by hand
before committing — the uv run pre-commit run --all-files above.
Prefix any --python <version> command with
UV_PROJECT_ENVIRONMENT=.venv-<version>, naming the interpreter that
command selects — .venv-3.11 for --python 3.11, .venv-pypy3.11 for
--python pypy3.11. Without it, uv run --python <version> removes
.venv, builds it again on that interpreter and with that command’s own
group set, and leaves it there: a run given --no-default-groups --group test leaves pre-commit out of what is then the project’s environment.
uv sync restores it. A --no-project command builds an ephemeral
environment rather than .venv and needs none of this: nothing rebuilds
the project’s own environment for the prefix to protect.
The editor¶
.vscode/settings.json and .vscode/extensions.json are tracked, and they
hold no preference: the recommended extensions are the tools
.pre-commit-config.yaml already runs, and the settings put the fixing ones
on save. Installing them is optional and changes nothing about what a local
run enforces — what they buy is learning of a finding while typing rather
than at the local run that trips over it.
Anything machine-local — an interpreter path, a telemetry answer, a theme — belongs in the editor’s own user settings instead, those two files being read by every checkout of this repository.
Reproducing what CI runs¶
Each command below is the one a CI job runs, verbatim. Keep this section true when a workflow changes.
os-ubuntu.yml, os-macos.yml and os-windows.yml, the suite job of
each — the suite, on one cell of a platform matrix. --no-cov undoes the
--cov addopts carries: a cell asks whether one (image, interpreter)
pair passes, and the coverage job below is where coverage is measured
once, gated, and reported instead:
uv run --locked --no-default-groups --group test pytest --no-cov
test.yml, the coverage job — --cov is in addopts, so this and the
bare pytest above are the same measurement; the report options live in
[tool.coverage.report]’s show_missing and skip_covered, so the job
types nothing after pytest:
uv run --locked --no-default-groups --group test pytest
test.yml, the dist job — check the distribution files and install
one. A pull request builds its own files here. release.yml’s test job
calls this workflow with use-signed-dist, and the job then checks the
files reusable-build.yml built, signed and uploaded instead, which the
publish jobs download — so what the checks below judge is what an index
ends up serving, byte for byte. The export and the normalize_sdist.py
run are what put the commit’s own second into every member of the sdist —
uv_build writes 0 there and ignores SOURCE_DATE_EPOCH, so the
archive is the normalizer’s output rather than the backend’s;
normalize_sdist.py’s docstring has the measurement. sha256sum after
them is the digest a rebuild from the tag is compared against, per
RELEASING.md’s “Rebuild a release from its tag”. generate_sbom.py writes
the CycloneDX bill of materials into sbom/ and not dist/, an index
taking distribution files and the publish jobs handing it that artifact
whole; reusable-build.yml’s attest job signs the document beside the
two files on a release, and its timestamp is that same
SOURCE_DATE_EPOCH, so a rebuild from the tag answers with the same
bytes there too, until main changes what generate_sbom.py writes.
generate_sbom.py is btclib-org/.github’s, served from main, and reads
this tree from the working directory, so the commands fetch it first:
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
uv build
uv run --no-project --python 3.15 .github/scripts/normalize_sdist.py dist/
sha256sum dist/*
served=$(mktemp -d)
git clone --depth 1 --filter=blob:none --sparse \
https://github.com/btclib-org/.github "$served"
git -C "$served" sparse-checkout set .github/scripts
uv run --no-project --python 3.15 \
"$served"/.github/scripts/generate_sbom.py dist/ sbom/
uv run --locked --only-group check twine check --strict dist/*
uv run --locked --only-group check check-wheel-contents dist/*.whl
uv run --locked --only-group check pyroma --min 10 dist/*.tar.gz
A rehearsal’s build, in reusable-build.yml, first runs
.github/actions/dev-version, which rewrites pyproject.toml’s version
with the suffix version-check computed and re-locks, so that uv build
ships a version TestPyPI has not already seen. None of the three checks
mind — what they judge is metadata syntax, README rendering and metadata
quality, none of which the suffix changes.
The job then installs the wheel it just built and checked, alone, from an empty directory, and uses it:
tmp=$(mktemp -d)
cd "$tmp"
uv venv
uv pip install "$OLDPWD"/dist/*.whl
.venv/bin/python -c "
from decimal import Decimal
from importlib.metadata import requires, version
import json
import bitcoin_core_rpc as rpc
name = 'bitcoin-core-rpc'
print(version(name))
assert not requires(name), requires(name)
replies = []
def transport(request, timeout):
request_id = json.loads(request.data)['id']
replies.append(request_id)
body = {'jsonrpc': '2.0', 'id': request_id, 'result': 1.25}
return 200, json.dumps(body).encode()
client = rpc.BitcoinCoreRpcClient.from_chain(
'regtest', user='u', password='p', transport=transport
)
assert client.call('getbalance') == Decimal('1.25')
assert len(replies) == 1
"
lint.yml, the lint job — this file is the lint gate, so there is no
second list of tools anywhere:
uv run --locked --only-group lint pre-commit run --all-files
docs.yml, the docs job — and this one is worth running even when every
hook passes, because no hook reads reStructuredText: a docstring docutils
cannot parse fails the workflow while pre-commit is green. The steps after
the build read the pages it wrote, and run in this order:
uv run --locked --no-default-groups --group docs \
sphinx-build -n -W -b html docs/source docs/build/html
if grep -rn 'href="#\.\.\?/' docs/build/html --include='*.html'; then
echo "::error::the links above resolve to no page (unresolved relative path)"
exit 1
fi
uv run --locked --no-default-groups --group docs \
python .github/scripts/check_api_page.py docs/build/html
The grep makes the unresolved-link claim about the built pages rather
than about the configuration that keeps them resolvable. What myst renders
for a destination it cannot resolve is an anchor to an id no page has, and
-W reports it because docs/source/conf.py resolves the links the
included root files carry and suppresses no myst warning; the grep is
what still finds one the day a suppression goes back in.
check_api_page.py asks the built page for every name of
bitcoin_core_rpc.__all__, and docs/source/api.rst’s block of one
automodule per submodule is what makes each of them findable there.
What the check is for is a member dropped without a word, which no
warning and therefore no -W reports; the script’s own docstring names
the shape that does it.
codeql.yml has no line here, and it is the one gate that cannot: its jobs
run github/codeql-action and no command of this project’s, so reproducing
it locally means the CodeQL CLI and a database rather than a uv run. An
open pull request gets the analysis from the trigger; a branch without one
asks for it with gh workflow run codeql.yml --ref <branch>.
Another interpreter, which is what the matrix varies. Prefix it with
UV_PROJECT_ENVIRONMENT, or uv run --python <version> replaces .venv
with one built on that interpreter and the restricted group set and leaves
it there, which The environment and the gates above has:
UV_PROJECT_ENVIRONMENT=.venv-3.11 uv run --locked --no-default-groups \
--group test --python 3.11 pytest --no-cov
On pypy3.11 --no-cov guards against a measured defect rather than
only matching the matrix. In tests/client_test.py,
test_a_status_survives_a_body_that_is_no_reply’s too deep case and
test_a_reply_nested_too_deeply_to_parse each build a body nested past
sys.getrecursionlimit() so that client.py’s own
except RecursionError is what answers it; either alone, run under
pypy3.11 with coverage on, is enough to reproduce the warning named
below, and a body kept under the limit is not — the size of the rest of the
suite is not the trigger. Raising that RecursionError while coverage’s
pure Python tracer is installed — PyPy carries no C one — leaves
sys.gettrace() returning None afterward. Coverage’s own suppression
for exactly this shape (pytracer.py’s PyTracer.stop,
env.PYPY and self.in_atexit and tf is None) only applies once the
atexit-registered setattr that flips in_atexit has actually run;
pytest-cov stops coverage earlier, from a pytest_runtestloop wrapper
that calls finish() once the whole test loop is done, so the
suppression never fires under pytest and the mismatch prints instead as
CoverageWarning: Trace function changed, data is likely wrong. That
check runs once, at the end of whichever run included either test, which
is why the warning always reads as coming from the end of a run rather
than from the test that caused it, and fail_under then judges whatever
fraction of the run had already been recorded by that point — unstable
with pytest-randomly’s seed for that reason. A narrowed run does not
avoid it either: tests/conftest.py’s own relaxation of fail_under on
a narrowed session silences the floor, not the warning. Marking either
test pytest.mark.no_cover, pytest-cov’s own marker, trades the warning
for an honest miss instead: nothing else reaches client.py’s
RecursionError branch, so the floor fails on pypy3.11 and on CPython
alike, exit 1 either way — not a fix.
What gates a merge, and what only reports¶
lint.yml, test.yml, docs.yml and integration-bitcoind.yml produce the
required checks, and REPOSITORY.md reads the rule back from the
endpoint rather than restating it.
What an administrator’s merge skips, and what it does to the runs, is
REPOSITORY.md’s Required checks on main and Branch protection.
workflow |
when |
what it varies |
|---|---|---|
|
pull request, push |
— |
|
pull request, push |
— |
|
pull request, and |
— |
|
pull request |
— |
|
push to main |
— |
|
pull request, push |
Core’s two ends, then 5 chains |
|
pull request, push to main, and weekly |
2 languages |
|
weekly, a release |
2 ubuntu images × 8 interpreters |
|
weekly, a release |
2 macOS images × 8 interpreters |
|
weekly, a release |
2 Windows images × 8 interpreters |
|
weekly, push to main |
— |
|
weekly |
3 images × the floor and the ceiling, upgraded |
|
weekly |
the floor interpreter, dependencies at their floors |
|
weekly |
every Core major it lists, then 5 chains on the newest |
|
weekly |
— |
|
weekly |
— |
|
weekly |
— |
|
weekly, a release |
what PyPI serves |
|
weekly |
the latest release’s sdist, rebuilt |
|
a tag |
the workflows it calls |
Which workflows that last row covers is
grep -n 'uses: \./\.github/workflows/' .github/workflows/release.yml,
not a list here: a list restated is one more thing to keep true.
Those gates run one image on one interpreter: ubuntu-latest, and the
version .python-version names. claude-review gates nothing: its own
header says it must not become a required check, a review that gates a
merge making a model’s judgement a branch rule.
api-break gates nothing either: it sets the api-break label on a pull
request that breaks the public API, and its own header says the label is
advice for a reviewer.
verified-signatures.yml reports after each push to main whether every
commit pushed is verified; the standard’s Signatures has the
rule.
Which day each of the rest runs is section 10 of the organization
standard, in btclib-org/.github, and not this file’s to restate — one
calendar covering the organization is one thing to remember.
Why so little gates is the ceiling on concurrent jobs the plan puts on the
whole organization, and REPOSITORY.md’s Plan-gated settings is where
that figure lives, beside the command that re-derives it. The platform
sweeps on every commit would ask for more than the ceiling between them, so
a pull request would spend its wall clock waiting for a slot rather than
running anything. At that ceiling a second image before a review buys a
rarer answer at the price of every review, and macOS is the sharpest case:
those cells wait for a runner far longer than they run.
What the sentinels vary, they vary whole. os-ubuntu runs the images
and the interpreters the gate does not sweep and the cell it does, and
bitcoind runs every Core major it lists, the two it gates on included. A
matrix with the gate’s cells cut out of it is one nobody can read the shape
of, and whoever asked what ran would have to re-derive the hole from the
gate.
windows-latest is in os-windows rather than on the gate, and the
platform-conditional branch it answers for is the datadir table in
default_datadir, whose rows the suite drives by patching sys.platform —
every row but the running one, so %APPDATA% and the Path.home() under it
are asked for real only on a Windows runner. That question does not vary
with the architecture the interpreter targets, which is why one row of that
matrix answers it and the rest are there for the standard library beneath.
os-ubuntu, os-macos and os-windows hold the dependencies at the lock
and move the platform; deps-latest moves both, and one variable each is
what lets the pair be read as a difference — os-macos.yml’s header states
that reading for its own column, and it is the same on the other two. Every
workflow here also takes workflow_dispatch, gates included, claude-review
and scorecard excepted — grep -c workflow_dispatch: .github/workflows/*.yml
is what says so, and for the three image workflows it is the only way to ask
about a branch at all. claude-review takes none because its one job
calls a workflow whose two jobs read the pull request or the comment
that triggered them, so a manual run would start with nothing to read.
scorecard takes none because its triggers are
the action’s rather than this section’s: ossf/scorecard-action names push
and schedule as supported and calls workflow_dispatch experimental.
codeql runs on a pull request as well as on main and its weekly
schedule, and it produces a check no rule requires: the analysis reaches
the branch while a finding is still cheap to answer, without a merge
waiting on the slots it holds. What reads a branch beside it is zizmor, a
pre-commit hook and therefore part of lint, which audits these
workflows for an injected expression. REPOSITORY.md has the trade in
full. codeql is also the one gate release does not call, a tag
publishing the tree those checks already passed.
Mutation testing¶
mutation.yml asks the question coverage cannot: a line the suite executes
is not a line the suite checks. It gates nothing and runs weekly; the
configuration is the single source of the scope and the test command.
uv run --locked --no-default-groups --group test --group mutation \
cosmic-ray baseline .github/mutation/bitcoin_core_rpc.toml
uv run --locked --no-default-groups --group test --group mutation \
cosmic-ray init .github/mutation/bitcoin_core_rpc.toml \
bitcoin_core_rpc.sqlite
uv run --locked --no-default-groups --group test --group mutation \
cr-filter-operators bitcoin_core_rpc.sqlite \
.github/mutation/bitcoin_core_rpc.toml
uv run --locked --no-default-groups --group test --group mutation \
cosmic-ray exec .github/mutation/bitcoin_core_rpc.toml \
bitcoin_core_rpc.sqlite
uv run --locked --no-default-groups --group test --group mutation \
cr-report --surviving-only --show-diff bitcoin_core_rpc.sqlite
The session writes each mutation into the client source and restores it afterwards, so nothing else may read the file while it runs.
A Dependabot uv pull request¶
Dependabot’s uv ecosystem rewrites uv.lock alone. Where a bump moves a
package that .clusterfuzzlite/requirements.txt pins, the uv-export
hook fails the lint job. An owner, as GOVERNANCE.md names them,
then commits the hook’s output to the pull request’s branch before it
lands, signed and signed off. On a checkout of that branch:
uv run --locked --only-group lint pre-commit run uv-export --all-files
git commit -S -s -m "Export .clusterfuzzlite/requirements.txt from uv.lock" \
.clusterfuzzlite/requirements.txt
git push origin HEAD:<branch>
The hook exits 1 when it rewrites the file. The push is a plain one, never a force, so a branch that moved meanwhile refuses it.
The commit is made by hand, not by a bot: the ci: block of
.pre-commit-config.yaml says why.
The cost is that Dependabot stops rebasing a pull request once extra
commits have been pushed to it, as
GitHub’s documentation
says. @dependabot recreate in a comment rebuilds the branch without the
commit, which is then made again.
A live node¶
integration-bitcoind.yml is the one claim the recorded replies cannot make.
Against a bitcoind of your own — it runs on a regtest chain in a temporary
datadir, on Core’s own rpc port, and leaves nothing behind:
uv run --locked --no-default-groups \
python .github/scripts/rpc_smoke.py \
--bitcoind /path/to/bitcoind --core-version 31.2 --protocol 2.0
--protocol is asserted rather than derived: what the workflow’s matrix
pins is that Core v27 answers JSON-RPC 1.1 and the current release answers
2.0, and a node that stopped doing so has to fail this rather than be
accommodated by it.
--chain is the other mode, one node at a time and no chain generated on
it: it starts a node of main, test, testnet4 or signet with no peer
reachable at all, and checks only that Core still accepts -chain=<name>,
reports it back, and passes assert_chain for it:
uv run --locked --no-default-groups \
python .github/scripts/rpc_smoke.py \
--bitcoind /path/to/bitcoind --core-version 31.2 --chain testnet4
The secrets baseline¶
detect-secrets reads .secrets.baseline to decide which findings have
already been reviewed, and which plugins run at all. Adding a credential
shaped literal to the tests means regenerating it:
uv run --locked --only-group lint pre-commit run detect-secrets --all-files
uvx detect-secrets scan --baseline .secrets.baseline
Read the diff before committing it: a new entry is a finding somebody has
to have looked at, which is the whole point of a baseline over an
exclusion. The one exclusion is a filter on a rev: line frozen to a sha:
on a line frozen to a tag, autoupdate rewrites the comment and drops a
pragma.