phantom/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-04-29 14:59:39 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge bitcoin/bitcoin#30142: doc: add guidance for RPC to developer notes
Some checks are pending
CI / test each commit (push) Waiting to run
Details
CI / macOS 14 native, arm64, no depends, sqlite only, gui (push) Waiting to run
Details
CI / macOS 14 native, arm64, fuzz (push) Waiting to run
Details
CI / Win64 native, VS 2022 (push) Waiting to run
Details
CI / Win64 native fuzz, VS 2022 (push) Waiting to run
Details
CI / ASan + LSan + UBSan + integer, no depends, USDT (push) Waiting to run
Details

Browse source 
c6eca6f396 doc: add guidance for RPC to developer notes (tdb3)

Pull request description:

  Adds guidance statements to the RPC interface section of the developer notes with examples of when to implement `-deprecatedrpc=`.

  Wanted to increase awareness of preferred RPC implementation approaches for newer contributors.

  This implements some of what's discussed in https://github.com/bitcoin/bitcoin/issues/29912#issuecomment-2081678433

  Opinions may differ, so please don't be shy.  We want to make RPC as solid/safe as possible.

  Examples of discussions where guidelines/context might have added value:
  https://github.com/bitcoin/bitcoin/pull/30212#issuecomment-2347371722
  https://github.com/bitcoin/bitcoin/pull/29845#discussion_r1571053657
  https://github.com/bitcoin/bitcoin/pull/30381#pullrequestreview-2160865613
  https://github.com/bitcoin/bitcoin/pull/29954#issuecomment-2103628952
  https://github.com/bitcoin/bitcoin/pull/30410#pullrequestreview-2167870869
  https://github.com/bitcoin/bitcoin/pull/30713
  https://github.com/bitcoin/bitcoin/pull/30381
  https://github.com/bitcoin/bitcoin/pull/29060#pullrequestreview-2406688998

ACKs for top commit:
  l0rinc:
    ACK c6eca6f396
  fjahr:
    ACK c6eca6f396
  maflcko:
    lgtm ACK c6eca6f396
  jonatack:
    ACK c6eca6f396

Tree-SHA512: 01a98a8dc0eb91762b225d3278cdb4a5e380ceb7486fd096b4ad9122bed859cea8584d8996d3dce51272fdb792f4a793a1bd1c5445efeb87f0a30f9b6e59a790
This commit is contained in:
merge-script 2025-03-21 13:47:48 +08:00
commit b43cfa20fd
No known key found for this signature in database
GPG key ID: 2EEB9F5CC09526C1
1 changed files with 6 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/developer-notes.md
View file

@ -1468,6 +1468,12 @@ A few guidelines for introducing and reviewing new RPC interfaces:
- *Rationale*: JSON strings are Unicode strings, not byte strings, and
RFC8259 requires JSON to be encoded as UTF-8.
A few guidelines for modifying existing RPC interfaces:
- It's preferable to avoid changing an RPC in a backward-incompatible manner, but in that case, add an associated `-deprecatedrpc=` option to retain previous RPC behavior during the deprecation period. Backward-incompatible changes include: data type changes (e.g. from `{"warnings":""}` to `{"warnings":[]}`, changing a value from a string to a number, etc.), logical meaning changes of a value, or key name changes (e.g. `{"warning":""}` to `{"warnings":""}`). Adding a key to an object is generally considered backward-compatible. Include a release note that refers the user to the RPC help for details of feature deprecation and re-enabling previous behavior. [Example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc/src/rpc/blockchain.cpp#L1316-L1323).
- *Rationale*: Changes in RPC JSON structure can break downstream application compatibility. Implementation of `deprecatedrpc` provides a grace period for downstream applications to migrate. Release notes provide notification to downstream users.
Internal interface guidelines
-----------------------------