#35395 doc: Improve test suite dependencies documentation
https://github.com/bitcoin/bitcoin/pull/35395 · · +40/-67 in 7 files, 3 commits · labels: Docs, Tests
Goal
- Consolidate functional test dependency instructions into a central reference to fix discrepancies across OS docs
- Helps contributors set up test suite dependencies reliably across different platforms
This PR centralizes functional test suite dependency documentation into test/README.md and replaces OS-specific test dependency sections in build docs with cross-references. It introduces a summary table covering package managers and dependency names across Debian/Ubuntu, macOS, Windows, FreeBSD, NetBSD, and OpenBSD, while clarifying Python UTF-8 mode settings.
Problem: Test dependency instructions were duplicated and inconsistent across individual OS build docs. Specific modules like pycapnp lacked OS-specific instructions, while pyzmq package naming conventions were inaccurately described.
Category: Documentation (#4 of 9)
P3 · cleanup
- P3 because it prevents doc rot by unifying scattered and inaccurate test dependency instructions
- Provides contributors with a reliable cross-platform reference for optional test packages
Improves test dependency documentation across six OS build guides and test/README.md, fixing missing and inaccurate instructions for optional modules like pycapnp and pyzmq.
Membership: The PR exclusively updates documentation files in doc/ and test/README.md.
Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 0
Category: Test infrastructure (#40 of 45)
P4 · cleanup
- P4 because it only updates test prerequisite documentation
- Does not modify test execution, harnesses, or test framework scripts
P4 because the PR touches only documentation for test prerequisites rather than the test runner, harnesses, or test framework machinery.
Membership: Labeled Tests by maintainers and modifies test/README.md regarding functional test requirements.
Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 0
Reviewability: Ready
- Ready to review: merges cleanly, CI passes, and previous feedback has been addressed
The branch is rebased, CI is clean, and the author addressed reviewer feedback in the latest push.
Author status: active, rebased and pushed the table compromise on 2026-09-02
Open concerns:
- fanquake objected to removing self-contained copy-paste instructions from OS-specific build guides in favor of centralized cross-references.
Resolved concerns:
- maflcko suggested consolidating the disparate package names into a concise Markdown table, which hebasto adopted in test/README.md.
- Clarification of pip vs. system package manager vs. virtual environment usage was incorporated into test/README.md.
Agreement: Mild
- General support for unifying optional test dependency instructions
- Resolved objection about lost package names by adding a cross-platform package table (fanquake, maflcko)
- Concept approval without stated reasons (l0rinc)
Mild; maflcko supports the centralized table compromise, but fanquake objected to removing copy-paste commands from OS build guides
maflcko provided multiple ACKs and helped shape the compromise table in test/README.md, but fanquake voiced skepticism about removing OS-specific commands from the build docs, leaving a nonblocking approach objection open.
- fanquake: 'Looks like you've just removed immediately usable OS specific instructions, and replaced them with general ones, just forcing devs to go and find the same info?'
- maflcko: 'review ACK c14f888996d45bc60af4a9e7023d836dff66bcb9'
Objections:
| Reviewer | Kind | Harm | Status | Blocking | Author replied | Quote |
|---|---|---|---|---|---|---|
| fanquake | approach | Removes immediately copy-pasteable OS-specific install commands from build guides, forcing developers to look up dependencies elsewhere | open | no | yes | 2026-07-08: 'I still don't quite understand how removing working instructions is an "improvement", especially given the rationale is that it's impossible to maintain individual package names (even though we do it everywhere else just fine).' |
Support:
- maflcko: Favored deduplication across OS build guides and suggested the consolidated table format
- l0rinc: Concept ACK for documenting dependencies [not substantive]
Participants: fanquake (objection), maflcko (support), l0rinc (support), sedited (neutral)
State derived from the lists: nonblocking objection open (fanquake)
Review verdicts (DrahtBot): 0 (+1)
Files
59 lines under test/bench/ci.
- test/README.md +30/-29
- doc/build-netbsd.md +1/-13
- doc/build-windows-msvc.md +2/-8
- doc/build-freebsd.md +1/-6
- doc/build-osx.md +1/-6
- doc/build-openbsd.md +1/-5
- doc/build-unix.md +4/-0
Card
This PR consolidates functional test dependency documentation across six OS-specific build guides into a single reference table in test/README.md. It fixes outdated and missing notes for optional Python test modules like pycapnp, pyzmq, and sqlite3. Review discussion is mildly divided: maflcko supported the consolidation and suggested the cross-platform table, while fanquake objected that removing package commands from OS-specific guides degrades copy-paste convenience for builders. The PR is ready for review following a rebase that incorporated the table compromise.