Documentation

PRPriorityReviewabilityReviewsAgreementSize
(+)#36101 purpleKarrot doc: Add an error handling strategyP2 · unblocks #34931Waiting on author0 -3Blocked124
  • Define a project-wide error handling strategy for Bitcoin Core
  • Resolve repeated debates across validation and subsystem reviews on handling errors and defects
  • P2 because it provides needed architectural guidance for multiple open subsystem PRs
  • Saves developer time by resolving recurring debates over error handling patterns across the codebase
  • Ready for review
  • Concept approval for having a unified error handling strategy (sedited, josibake, willcl-ark)
  • Unaddressed objection: contradicts existing util::Expected practice and adds tech debt (ajtowns)
  • Unaddressed objection: broad exceptions introduce deadlock risks during shutdown (maflcko)
  • Objection: aborting on defects risks wallet corruption and node instability (furszy, mzumsande, stickies-v)
  • Objection: exceptions introduce unpredictable side effects and invisible control flow (l0rinc)
  • 124 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 0 lines removed in total
  • 1 files, 1 commits
(+)#35858 pablomartin4btc doc: Add privacy.md consolidating network privacy recommendationsP2 · cleanupReady0Mild79
  • Consolidate network privacy advice into a single reference guide for node operators
  • Document how to use private transaction broadcast along with its limitations, prerequisites, and RPCs
  • P2 after comparing with the other PRs here (assessed alone as P3): Raised to P2: documents a privacy feature's prerequisites and scope limits, where absent/fragmented guidance can lead operators to over-trust private broadcast.
  • P3 because it consolidates fragmented and duplicated privacy advice across multiple network docs
  • Helps node operators understand the prerequisites and scope limitations of private transaction broadcast
  • Ready to review
  • Concept approval without stated reasons (jonatack)
  • Nonblocking objection: guidance on multi-network deanonymization is incomplete or misleading (jonatack)
  • 79 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 19 lines removed in total
  • 4 files, 2 commits
(+)#36348 jpk68 doc/i2p: mention -privatebroadcast bypasses persistent addressP2 · bug fixWaiting on author1 (+1)Strong11
  • Clarify in I2P documentation that private broadcast connections use transient addresses
  • Help node operators understand exactly when their persistent I2P identity is exposed
  • P2 after comparing with the other PRs here (assessed alone as P3): Raised to P2: corrects privacy-relevant documentation (persistent I2P identity exposure, wallet txs not covered) that could otherwise lead operators to a wrong conclusion; same consequence class as #35858.
  • P3 because it corrects misleading documentation about persistent I2P address exposure
  • The change is marginal and only affects operators checking I2P privacy behavior
  • Ready for review
  • Broad support with minor terminology suggestions
  • Concept support with suggestions on expanding scope details (jonatack)
  • ACKed with open wording suggestions on transient addresses (andrewtoth)
  • Thinks the clarification may be pedantic noise for users but still fine (davidgumberg)
  • 11 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 1 lines removed in total
  • 1 files, 1 commits
(+)#35518 fernandguil doc: document -blocknotify, -walletnotify and other -*notify optionsP3 · user requestAuthor silent 124d1Positive21
  • Document that -*notify startup options run asynchronously without ordering guarantees
  • Prevent race conditions in user scripts by directing consumers to query state via RPC instead
  • P3 because it clarifies notification execution behavior to resolve long-standing integration issues
  • Prevents external script developers from assuming sequential order and encountering race conditions
  • Author silent for 91 days; responses to new reviews may take time
  • Approval without stated reasons after earlier comments were addressed (sedited)
  • Awaiting promised review comparing with existing branch (willcl-ark)
  • 21 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 0 lines removed in total
  • 2 files, 1 commits
(+)#35480 fernandguil doc: document ZMQ notification behavior during reorgs and evictionsP3 · cleanupWaiting on author0Neutral15 + 59 tests
  • Document ZMQ notification behavior during chain reorganizations and mempool evictions
  • Gives external client developers clear notification guarantees without reading C++ internals
  • P3 because it documents existing ZMQ reorg and mempool eviction behavior for downstream developers
  • The benefit is targeted specifically at external clients relying on ZMQ notifications
  • Ready to review
  • No review verdicts recorded
  • Nobody has spoken directly in favor yet, while earlier objections were settled
  • Suggests condensing the explanation of transaction removal notifications (sedited)
  • Suggests dropping the new reorg functional test since existing tests cover ordering (sedited)
  • 15 lines added or modified outside tests
  • 59 lines added or modified in tests
  • 0 lines removed in total
  • 2 files, 2 commits
(+)#32278 vasild doc: better document NetEventsInterface and the deletion of "CNode"sP3 · cleanupWaiting on author0 (+1)Strong61
  • Document network connection lifecycles and event sequences for developers
  • Help developers avoid concurrency bugs and memory leaks when touching networking code
  • P3 because it helps developers avoid subtle concurrency and memory errors
  • The benefit is limited to internal code documentation without behavioral changes
  • Ranking pass: Internal developer documentation with no user-facing misdirection; sits below the privacy/config docs despite its high standalone score.
  • Waiting on author to respond on whether the pull request should be closed
  • Support for clear documentation improvements (w0xlt)
  • Suggests closing due to low reviewer interest and limited documentation usefulness (sedited)
  • Earlier documentation phrasing and concurrency questions were addressed (ajtowns, laanwj)
  • 61 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 6 lines removed in total
  • 1 files, 1 commits
(+)#30361 ryanofsky doc: Drop description of LogError messages as fatalP3 · cleanupWaiting on author0 (+1) -2Blocked5
  • Align developer logging guidelines with actual codebase practice
  • Reduce confusion during development by not reserving error logs strictly for fatal shutdowns
  • P3 after comparing with the other PRs here (assessed alone as P4): Raised to P4->P3: the current text is factually wrong against the codebase (58/129 LogError calls fatal, per #30348) and keeps re-triggering review debates, which is more than cleanup.
  • P4 because it only loosens internal developer guidance for logging conventions
  • It does not correct misleading user-facing documentation or affect node behavior
  • Wait for the author to respond to multiple standing objections on whether to close this pull request
  • Opposed by reviewers who prefer fixing call sites over lowering doc standards (maflcko, ajtowns)
  • Unaddressed objection: unnecessary given progress toward original guidelines, recommends closing (sedited)
  • Support as a slight improvement to the documentation (l0rinc)
  • 5 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 6 lines removed in total
  • 1 files, 1 commits
(+)#36704 fanquake doc: fix docs and enable `-Wdocumentation-unknown-command`P4 · cleanupReady0Crickets36
  • Catch misspelled and unrecognized Doxygen tags automatically during compilation
  • Fix existing Doxygen syntax mistakes and formatting errors across the codebase
  • P4 because syntax cleanup and typo fixes do not change underlying technical meaning
  • Ensures comments are correctly formatted and parsed by documentation tooling
  • Ready for review
  • Nothing known that would invalidate a review now
  • No review verdicts recorded
  • No substantive review comments or feedback yet
  • Awaiting initial community review
  • 36 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 30 lines removed in total
  • 13 files, 3 commits
(+)#36612 maflcko doc: Merge all BSD build docs back into build-unix.mdP4 · cleanupReady1Positive41
  • Avoid maintaining duplicate build instructions across separate BSD documents
  • Reduces maintenance overhead when build system instructions change
  • P4 because it is a routine cleanup deduplicating boilerplate across BSD guides
  • Does not fix incorrect build instructions or document missing features
  • Ready to review
  • Approval without stated reasons (hebasto)
  • Clarification on integrating NetBSD notes was answered by author (hebasto)
  • 41 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 347 lines removed in total
  • 6 files, 2 commits
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.
Ranking pass (2026-11-01): all PRs here were compared with each other; 7 notes on review order, overlaps, and band changes.

Covers

Documentation as the primary change: developer notes, design documents, build and usage docs, release notes, RPC help text when the change is to the text rather than the interface, and code comments when a PR consists mainly of them. The Docs label is a strong prior.

Not docs: a code change that also updates its docs (that area).

What matters here

Wrong documentation first: text that would lead a user or developer to do the wrong thing, especially around security, backups, and configuration. Then missing documentation for something users hit often or that a design decision depends on (a design doc that unblocks a project counts as leverage). Then release notes completeness. Then clarity improvements to frequently read pages. Then typo and style fixes, which are P4 unless they fix a meaning.

generated 2026-11-02 01:17 UTC