doc: mention key removal in rpc interface modification #32867

pull rkrux wants to merge 1 commits into bitcoin:master from rkrux:rpc-deprecation changing 1 files +1 −1
  1. rkrux commented at 12:15 PM on July 3, 2025: contributor

    A discussion in a previous PR 32618 prompted me to add this note: #32618 (review)

    <!-- *** Please remove the following help text before submitting: *** Pull requests without a rationale and clear improvement may be closed immediately. GUI-related pull requests should be opened against https://github.com/bitcoin-core/gui first. See CONTRIBUTING.md -->

    <!-- Please provide clear motivation for your patch and explain how it improves Bitcoin Core user experience or Bitcoin Core developer experience significantly: * Any test improvements or new tests that improve coverage are always welcome. * All other changes should have accompanying unit tests (see `src/test/`) or functional tests (see `test/`). Contributors should note which tests cover modified code. If no tests exist for a region of modified code, new tests should accompany the change. * Bug fixes are most welcome when they come with steps to reproduce or an explanation of the potential issue as well as reasoning for the way the bug was fixed. * Features are welcome, but might be rejected due to design or scope issues. If a feature is based on a lot of dependencies, contributors should first consider building the system outside of Bitcoin Core, if possible. * Refactoring changes are only accepted if they are required for a feature or bug fix or otherwise improve developer experience significantly. For example, most "code style" refactoring changes require a thorough explanation why they are useful, what downsides they have and why they *significantly* improve developer experience or avoid serious programming bugs. Note that code style is often a subjective matter. Unless they are explicitly mentioned to be preferred in the [developer notes](/doc/developer-notes.md), stylistic code changes are usually rejected. -->

    <!-- Bitcoin Core has a thorough review process and even the most trivial change needs to pass a lot of eyes and requires non-zero or even substantial time effort to review. There is a huge lack of active reviewers on the project, so patches often sit for a long time. -->

  2. DrahtBot added the label Docs on Jul 3, 2025
  3. DrahtBot commented at 12:15 PM on July 3, 2025: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32867.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    ACK maflcko, stickies-v, glozow

    If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  4. rkrux commented at 12:16 PM on July 3, 2025: contributor

    I want to mention about how long is the deprecation/grace period generally but I don't know right now. Suggestions welcome.

  5. Sammie05 commented at 1:55 AM on July 13, 2025: none

    I checked this branch locally and saw that it removes -Werror=dev from the CMake generation step. Just to understand better: is this to prevent CI from failing on dev warnings? Looks reasonable to me, but curious if it’s meant to be temporary or permanent.

  6. maflcko commented at 6:46 AM on July 14, 2025: member

    lgtm ACK e7b1c33b41334a9c2ce80033d92e3fac466eb70c

  7. achow101 requested review from achow101 on Oct 22, 2025
  8. in doc/developer-notes.md:1429 in e7b1c33b41 
    1425 | @@ -1426,7 +1426,7 @@ A few guidelines for introducing and reviewing new RPC interfaces:
1426 |  
1427 |  A few guidelines for modifying existing RPC interfaces:
1428 |  
1429 | -- 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).
1430 | +- 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, key name changes (e.g. `{"warning":""}` to `{"warnings":""}`), or key removal from the RPC interface. 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).
    stickies-v commented at 3:40 PM on October 22, 2025:

    The next sentence seems like a more logical place to put this.

    - 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, key name changes (e.g. `{"warning":""}` to `{"warnings":""}`). Adding or removing 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).
    rkrux commented at 4:21 PM on October 22, 2025:

    Although putting it in the next sentence does reduce verbosity but by putting it there would give the impression that key removal is backward-compatible, which I don't think is correct?

    stickies-v commented at 7:38 AM on October 23, 2025:

    Sorry, that was terrible suggestion. I wanted to keep the language consistent.

    - 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, key name changes (e.g. `{"warning":""}` to `{"warnings":""}`), or removing a key from an object. 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).
    rkrux commented at 9:40 AM on October 23, 2025:

    Done

  9. doc: mention key removal in rpc interface modification
    A discussion in a previous PR 32618 prompted me to add this note.
    944e5ff848
  10. rkrux force-pushed on Oct 23, 2025
  11. maflcko commented at 9:46 AM on October 23, 2025: member

    lgtm ACK 944e5ff848f656d2ee6202b2330f3ae178ad0fbe

  12. stickies-v commented at 12:20 PM on October 23, 2025: contributor

    ACK 944e5ff848f656d2ee6202b2330f3ae178ad0fbe

  13. glozow commented at 3:44 PM on October 28, 2025: contributor

    lgtm ACK 944e5ff848f656d2ee6202b2330f3ae178ad0fbe

  14. glozow merged this on Oct 28, 2025
  15. glozow closed this on Oct 28, 2025
  16. sedited referenced this in commit f50d90fcbb on Oct 29, 2025
  17. stickies-v referenced this in commit a785fe6759 on Nov 5, 2025
  18. stringintech referenced this in commit b82132c4d1 on Nov 6, 2025
  19. yuvicc referenced this in commit f620a2206b on Nov 16, 2025
  20. Kino1994 referenced this in commit 2fed7d257a on Jun 28, 2026
  21. BigcoinBGC referenced this in commit ed84543662 on Jun 30, 2026
  22. Kino1994 referenced this in commit 86c3e69fd1 on Aug 19, 2026
  23. bitcoin locked this on Oct 28, 2026
Contributors
rkruxDrahtBotSammie05maflckostickies-vglozow


achow101

Labels
Docs
Linked (view graph)
#32618 wallet: Remove ISMINE_WATCHONLY and watchonly from RPCs
github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-10-30 09:41 UTC