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.

[![calendar versioning:

yyyy.m.d](https://img.shields.io/badge/cal_ver-yyyy.m.d-1674b1.svg?logo=calver)](https://calver.org/) uv format:ruff lint:ruff docstrings:ruff type check:mypy lint:markdownlint-cli2 pre-commitenabled GitHub repository:btclib-org/bitcoin-core-rpc

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

test

pull request, push

—

lint, docs

pull request, push

—

claude-review

pull request, and @claude in a comment

—

api-break

pull request

—

verified-signatures

push to main

—

bitcoind

pull request, push

Core’s two ends, then 5 chains

codeql

pull request, push to main, and weekly

2 languages

os-ubuntu

weekly, a release

2 ubuntu images × 8 interpreters

os-macos

weekly, a release

2 macOS images × 8 interpreters

os-windows

weekly, a release

2 Windows images × 8 interpreters

scorecard

weekly, push to main

—

deps-latest

weekly

3 images × the floor and the ceiling, upgraded

deps-oldest

weekly

the floor interpreter, dependencies at their floors

bitcoind

weekly

every Core major it lists, then 5 chains on the newest

links

weekly

—

mutation

weekly

—

fuzz

weekly

—

pypi-install

weekly, a release

what PyPI serves

sdist-rebuild

weekly

the latest release’s sdist, rebuilt

release

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.