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)
2. DrahtBot added the label Docs on Jul 3, 2025
3. 
   DrahtBot commented at 12:15 pm on July 3, 2025: contributor

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

   Code Coverage & Benchmarks

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

   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.

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.

   0- 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.

   0- 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
rkrux DrahtBot Sammie05 maflcko stickies-v glozow

Review Requested
achow101

Labels
Docs