doc: add feature deprecation and removal process to developer notes
What the developer wrote
Authored by Guillermo Fernandes
doc: add feature deprecation and removal process to developer notes
Adds a dedicated "Feature deprecation and removal process" section to
developer-notes.md covering the deprecation lifecycle for RPC methods,
startup options, REST interface, and ZMQ.
Closes #31980
What changed, and why it matters
This commit only adds documentation to the developer notes. It describes the project's rules for phasing out old features (RPC methods, startup options, REST endpoints, and ZMQ topics) over time. No code behavior changed, so there is no security issue or vulnerability here.
No action needed; this is a documentation-only policy commit.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch is a pure documentation addition to doc/developer-notes.md. It introduces a ‘Feature deprecation and removal process’ section that formalizes grace periods, release-note requirements, and warning/help-text conventions for deprecated RPC methods, startup options, REST interface features, and ZMQ topics. No executable code is modified.
Changed components
doc/developer-notes.mdInspect captured patch +40 / −0
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 18691811..af0a4415 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -1356,6 +1356,46 @@ A few guidelines for modifying existing RPC interfaces:
- *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.
+## Feature deprecation and removal process
+
+Bitcoin Core uses a structured process for deprecating and removing features to give
+downstream users and applications time to migrate.
+
+### General principles
+
+- The minimum deprecation **grace period** for a feature that is going to be removed is one
+ major release.
+- Any deprecation or removal must come with a release note.
+
+### RPC methods and fields
+
+- To deprecate an entire RPC method, gate the old behavior behind `-deprecatedrpc=<feature>`.
+ Deprecated features should remain accessible via this flag during the grace period so
+ downstream users are not immediately broken.
+- The RPC help text must mention the deprecation and the `-deprecatedrpc=<feature>` flag
+ that re-enables it. For example:
+ ```
+ "\nDeprecated in v25.0, use the `newfoo` RPC instead. Start bitcoind with"
+ " `-deprecatedrpc=foo` to continue using this RPC.\n"
+ ```
+
+### Startup options
+
+- To deprecate a startup option, emit a warning via `LogWarning` or `InitWarning` when the
+ option is used, so users are notified at startup.
+- Update the option's help text to indicate it is deprecated and, if applicable, will be
+ removed in a future release.
+
+### REST interface
+
+- Deprecated REST endpoints or behaviors should be documented in `doc/REST-interface.md`
+ with the version they were deprecated.
+
+### ZMQ
+
+- Deprecated ZMQ topics or behaviors should be documented in `doc/zmq.md` with the version
+ they were deprecated.
+
## Internal interface guidelines
Internal interfaces between parts of the codebase that are meant to be
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.