highperfocused/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2026-05-27 22:34:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge bitcoin/bitcoin#35337: doc: add feature deprecation and removal process to developer notes

Browse Source 
2e9fdcc6da doc: add feature deprecation and removal process to developer notes (Guillermo Fernandes)

Pull request description:

  Closes #31980

  Adds a dedicated **"Feature deprecation and removal process"** section to `doc/developer-notes.md` covering the full deprecation lifecycle for all major feature categories.

  ## What's added

  **General principles**
  - Grace period is one major release (deprecated in N, removed in N+1)
  - Deprecation and removal both require release notes
  - Deprecated features should remain accessible via a re-enable flag during the grace period

  **Per-category guidance covering:**
  - RPC methods and fields (`-deprecatedrpc=<feature>` pattern, help text requirements, worked example pointing to #31278)
  - Startup options (`LogWarning`/`InitWarning` on use, help text update)
  - REST interface (document in `doc/REST-interface.md`)
  - ZMQ (document in `doc/zmq.md`)
  - Wallet settings (defer to RPC or startup option process depending on exposure)

  This consolidates the process that currently exists only implicitly across PRs and issue discussions into one place for contributors to reference.

ACKs for top commit:
  maflcko:
    lgtm ACK 2e9fdcc6da
  polespinasa:
    ACK 2e9fdcc6da
  stickies-v:
    ACK 2e9fdcc6da
  sedited:
    ACK 2e9fdcc6da

Tree-SHA512: 1d43df410664a45f937bcbd250664f13379168ca90e3024bea506e21a88177e201dcb4fadade705735099e3b8aaa2102a3080ad005bffb3aecb8f08d530d4277
This commit is contained in:
merge-script
2026-05-26 15:19:19 +02:00
parent a4157fc24a 2e9fdcc6da
commit 9c15022260
1 changed files with 40 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
doc/developer-notes.md
View File

@@ -1387,6 +1387,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