doc: mention key removal in rpc interface modification #32867

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: member

    lgtm ACK 944e5ff848f656d2ee6202b2330f3ae178ad0fbe

14. glozow merged this on Oct 28, 2025
15. glozow closed this on Oct 28, 2025

    ---

Contributors

rkruxDrahtBotSammie05maflckostickies-vglozow

Review Requested
achow101