From 40ac07ef45f6de0ac6a13e34797387a6ee140de9 Mon Sep 17 00:00:00 2001
From: tdb3 <106488469+tdb3@users.noreply.github.com>
Date: Sun, 2 Jun 2024 20:38:03 -0400
Subject: [PATCH] doc: add guidance for RPC to developer notes

Adds deprecatedrpc guidance statement to the
RPC interface guidelines section.
---
 doc/developer-notes.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 952dbc77a0d..493fa2d94ae 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -1460,6 +1460,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 and reviewing existing RPC interfaces:
+
+- If an RPC is being changed in a backward-incompatible way, 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. A release note should be included that refers to RPC help for details of feature deprecation and re-enabling previous behavior. [Example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc31d2d263a03e46192922e3a7672e39d9/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
 -----------------------------