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

pull fernandguil wants to merge 1 commits into bitcoin:master from fernandguil:doc/deprecation-removal-process-v2 changing 1 files +40 −0
  1. fernandguil commented at 8:08 PM on May 20, 2026: contributor

    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.

  2. DrahtBot added the label Docs on May 20, 2026
  3. DrahtBot commented at 8:08 PM on May 20, 2026: 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/35337.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    ACK maflcko, polespinasa, stickies-v, sedited

    If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  4. in doc/developer-notes.md:1411 in c4b6103255 
    1406 | +- Include a release note.
1407 | +
1408 | +### Wallet settings
1409 | +
1410 | +- Wallet settings exposed as RPC methods follow the [RPC deprecation process](#rpc-methods-and-fields).
1411 | +- Wallet settings exposed as startup options follow the [startup option process](#startup-options).
    maflcko commented at 10:46 AM on May 21, 2026:

    I think this section is already clear and can be removed.

  5. maflcko approved
  6. maflcko commented at 10:47 AM on May 21, 2026: member

    lgtm, seems fine to document the status quo, if it helps devs.

    cc @polespinasa

  7. in doc/developer-notes.md:1366 in c4b6103255 
    1361 | +Bitcoin Core uses a structured process for deprecating and removing features to give
1362 | +downstream users and applications time to migrate.
1363 | +
1364 | +### General principles
1365 | +
1366 | +- The deprecation **grace period** is one major release. A feature deprecated in version N
    polespinasa commented at 11:07 AM on May 21, 2026: 
    - The minimum deprecation **grace period** for a feature that is going to be removed is one major release.

    I suggest this change because we had a lot of debate about deprecating meaning removing in the future (specially during the op_return drama). #32406 (comment) And there are cases of options being undeprecated, see #32423

    My definition of deprecating is that the use of X feature is not recommended and should be avoided. But that does not mean removal will happen.

    But I do think that all removals need a deprecation (grace) period.

    I think it is clear to state that here, as this is the position Core took in other cases, and I believe should continue be the case.

  8. in doc/developer-notes.md:1369 in c4b6103255 
    1364 | +### General principles
1365 | +
1366 | +- The deprecation **grace period** is one major release. A feature deprecated in version N
1367 | +  is expected to be removed in version N+1.
1368 | +- Deprecation must be announced in the release notes of the version in which it is introduced.
1369 | +- Removal must also be noted in the release notes of the version in which it occurs.
    polespinasa commented at 11:09 AM on May 21, 2026:

    This can be simplified by just:

    - Any deprecation or removal must come with a release note

    Imo this notes should be as short and clear as possible because if not, people does not read them.

  9. in doc/developer-notes.md:1375 in c4b6103255 
    1370 | +- Where possible, deprecated features should remain accessible via a re-enable flag during
1371 | +  the grace period so downstream users are not immediately broken.
1372 | +
1373 | +### RPC methods and fields
1374 | +
1375 | +- To deprecate an entire RPC method or a backward-incompatible change to an existing method,
    polespinasa commented at 11:10 AM on May 21, 2026:

    I don't think this includes backward-incompatible changes. The scope should keep focused on deprecation.

    Breaking changes are another different (and more complex) debate.

    maflcko commented at 11:44 AM on May 21, 2026:

    I don't see the difference, this is also mentioned in the pre-existing section directly above?

    polespinasa commented at 11:49 AM on May 21, 2026:

    Fair enough, didn't see the pre-existing section.

    In any case this duplicated the information provided in the section above. So we can maintain the scope to deprecation (I prefere this) or remove the previous section and move it here too.

  10. in doc/developer-notes.md:1376 in c4b6103255 
    1371 | +  the grace period so downstream users are not immediately broken.
1372 | +
1373 | +### RPC methods and fields
1374 | +
1375 | +- To deprecate an entire RPC method or a backward-incompatible change to an existing method,
1376 | +  gate the old behavior behind `-deprecatedrpc=<feature>`. During the grace period, users
    polespinasa commented at 11:11 AM on May 21, 2026:

    I think this line can finish after -deprecatedrpc=<feature> to keep it short.

  11. in doc/developer-notes.md:1378 in c4b6103255 
    1373 | +### RPC methods and fields
1374 | +
1375 | +- To deprecate an entire RPC method or a backward-incompatible change to an existing method,
1376 | +  gate the old behavior behind `-deprecatedrpc=<feature>`. During the grace period, users
1377 | +  must explicitly opt-in to the deprecated behavior using this flag.
1378 | +- The RPC help text must mention the deprecation, the planned removal version, and the
    polespinasa commented at 11:12 AM on May 21, 2026:

    Not the planned removal version, but the intention of removal. See as example: https://github.com/bitcoin/bitcoin/pull/32406/changes#diff-b1e19192258d83199d8adaa5ac31f067af98f63554bfdd679bd8e8073815e69dR879

  12. in doc/developer-notes.md:1381 in c4b6103255 
    1376 | +  gate the old behavior behind `-deprecatedrpc=<feature>`. During the grace period, users
1377 | +  must explicitly opt-in to the deprecated behavior using this flag.
1378 | +- The RPC help text must mention the deprecation, the planned removal version, and the
1379 | +  `-deprecatedrpc=<feature>` flag that re-enables it during the grace period.
1380 | +  See [example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc/src/rpc/blockchain.cpp#L1316-L1323).
1381 | +- Include a release note pointing users to the RPC help for details.
    polespinasa commented at 11:14 AM on May 21, 2026:

    That's already said in the general principles section

  13. in doc/developer-notes.md:1383 in c4b6103255 
    1378 | +- The RPC help text must mention the deprecation, the planned removal version, and the
1379 | +  `-deprecatedrpc=<feature>` flag that re-enables it during the grace period.
1380 | +  See [example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc/src/rpc/blockchain.cpp#L1316-L1323).
1381 | +- Include a release note pointing users to the RPC help for details.
1382 | +- In the removal release: remove the `-deprecatedrpc=` handling and the deprecated code path,
1383 | +  and note the removal in release notes. See [#31278](https://github.com/bitcoin/bitcoin/pull/31278)
    polespinasa commented at 11:14 AM on May 21, 2026:

    same, this is in the general principles

  14. in doc/developer-notes.md:1390 in c4b6103255 
    1385 | +
1386 | +### Startup options
1387 | +
1388 | +- To deprecate a startup option, emit a warning via `LogWarning` or `InitWarning` when the
1389 | +  option is used, so users are notified at startup.
1390 | +- Update the option's help text to indicate it is deprecated and will be removed in the next
    polespinasa commented at 11:14 AM on May 21, 2026:

    will be removed in a future release only if that the case

  15. in doc/developer-notes.md:1392 in c4b6103255 
    1387 | +
1388 | +- To deprecate a startup option, emit a warning via `LogWarning` or `InitWarning` when the
1389 | +  option is used, so users are notified at startup.
1390 | +- Update the option's help text to indicate it is deprecated and will be removed in the next
1391 | +  major release.
1392 | +- Include a release note.
    polespinasa commented at 11:15 AM on May 21, 2026:

    already said in general principles

  16. in doc/developer-notes.md:1393 in c4b6103255 
    1388 | +- To deprecate a startup option, emit a warning via `LogWarning` or `InitWarning` when the
1389 | +  option is used, so users are notified at startup.
1390 | +- Update the option's help text to indicate it is deprecated and will be removed in the next
1391 | +  major release.
1392 | +- Include a release note.
1393 | +- In the removal release: remove the option and its handling, and note the removal in release
    polespinasa commented at 11:15 AM on May 21, 2026:

    seems duplicated

  17. in doc/developer-notes.md:1400 in c4b6103255 
    1395 | +
1396 | +### REST interface
1397 | +
1398 | +- Deprecated REST endpoints or behaviors should be documented in `doc/REST-interface.md`
1399 | +  with the version they were deprecated and the planned removal version.
1400 | +- Include a release note.
    polespinasa commented at 11:15 AM on May 21, 2026:

    also general principles

  18. in doc/developer-notes.md:1399 in c4b6103255 
    1394 | +  notes.
1395 | +
1396 | +### REST interface
1397 | +
1398 | +- Deprecated REST endpoints or behaviors should be documented in `doc/REST-interface.md`
1399 | +  with the version they were deprecated and the planned removal version.
    polespinasa commented at 11:15 AM on May 21, 2026:

    only if it is planned to be removed and if the version is defined

  19. in doc/developer-notes.md:1405 in c4b6103255 
    1400 | +- Include a release note.
1401 | +
1402 | +### ZMQ
1403 | +
1404 | +- Deprecated ZMQ topics or behaviors should be documented in `doc/zmq.md` with the version
1405 | +  they were deprecated and the planned removal version.
    polespinasa commented at 11:16 AM on May 21, 2026:

    same as other comments

  20. in doc/developer-notes.md:1406 in c4b6103255 
    1401 | +
1402 | +### ZMQ
1403 | +
1404 | +- Deprecated ZMQ topics or behaviors should be documented in `doc/zmq.md` with the version
1405 | +  they were deprecated and the planned removal version.
1406 | +- Include a release note.
    polespinasa commented at 11:16 AM on May 21, 2026:

    general principles

  21. polespinasa commented at 11:16 AM on May 21, 2026: member

    thanks for taking a look into this :)

    concept ACK

    left some comments

  22. fernandguil commented at 3:45 PM on May 21, 2026: contributor

    Hi All, great to connect here.

    To @polespinasa comments: Thanks for the detailed review! Suggestions make sense: Agree on softening the grace period language — "minimum" is more accurate given that deprecation doesn't always mean removal will happen. Will consolidate the two release note bullets into one as suggested. Will remove the "backward-incompatible changes" scope from the RPC section to keep it focused on deprecation only. Will trim the per-category sections to remove anything already covered in General Principles — good catch on the duplication. "intention of removal" wording makes more sense than "planned removal version", noted. Will update startup options to say "if applicable, will be removed in a future release".

    To @maflcko comments: good point - the Wallet settings subset is redundant, I’ll remove it. On the RPC section overlapping with the pre-existing section above: I'll keep the scope strictly on deprecation (not backward-incompatible changes broadly) to avoid duplicating what's already there.

    I’ll update and push a new commit to the PR.

    Guillermo Fernandes X https://x.com/guillefernandes | LinkedIn https://www.linkedin.com/in/guillermofernandes/

    On May 21, 2026, at 7:49 AM, Pol Espinasa @.***> wrote:

    @polespinasa commented on this pull request.

    In doc/developer-notes.md https://github.com/bitcoin/bitcoin/pull/35337#discussion_r3280903030:

    • +Bitcoin Core uses a structured process for deprecating and removing features to give +downstream users and applications time to migrate.
    • +### General principles
    • +- The deprecation grace period is one major release. A feature deprecated in version N
    • is expected to be removed in version N+1. +- Deprecation must be announced in the release notes of the version in which it is introduced. +- Removal must also be noted in the release notes of the version in which it occurs. +- Where possible, deprecated features should remain accessible via a re-enable flag during
    • the grace period so downstream users are not immediately broken.
    • +### RPC methods and fields
    • +- To deprecate an entire RPC method or a backward-incompatible change to an existing method, Fair enough, didn't see the pre-existing section.

    In any case this duplicated the information provided in the section above. So we can maintain the scope to deprecation (I prefere this) or remove the previous section and move it here too.

    — Reply to this email directly, view it on GitHub https://github.com/bitcoin/bitcoin/pull/35337#discussion_r3280903030, or unsubscribe https://github.com/notifications/unsubscribe-auth/AJP757AEMPSQDF5UA2VFOUD433UNRAVCNFSM6AAAAACZGTN36CVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHM2DGMZWGYYTAOBWGU. Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub. You are receiving this because you authored the thread.

  23. maflcko commented at 4:46 PM on May 21, 2026: member

    Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

  24. fernandguil force-pushed on May 21, 2026
  26. DrahtBot added the label CI failed on May 21, 2026
  27. DrahtBot removed the label CI failed on May 21, 2026
  28. in doc/developer-notes.md:1369 in bd3ad347b9 
    1364 | +### General principles
1365 | +
1366 | +- The minimum deprecation **grace period** for a feature that is going to be removed is one
1367 | +  major release.
1368 | +- Any deprecation or removal must come with a release note.
1369 | +- Where possible, deprecated features should remain accessible via a re-enable flag during
    polespinasa commented at 8:39 AM on May 22, 2026:

    Maybe this could go in RPC methods and fields section together with the instruction mentioning -depractedrpc=<feature>.

    I don't think this apply for startup options. Do we have a re-enable flag on startup options? IIRC we only add (Deprecated) in the help message. (Or at least that's what I did in #31278)

  29. polespinasa commented at 8:40 AM on May 22, 2026: member

    Thanks for addressing feedback, looks pretty good to me now.

  30. in doc/developer-notes.md:1375 in bd3ad347b9 
    1370 | +  the grace period so downstream users are not immediately broken.
1371 | +
1372 | +### RPC methods and fields
1373 | +
1374 | +- To deprecate an entire RPC method, gate the old behavior behind `-deprecatedrpc=<feature>`.
1375 | +- The RPC help text must mention the deprecation, the intention of removal, and the
    stickies-v commented at 1:51 PM on May 22, 2026:

    ", the intention of removal" that seems not practical, would just leave it out. The fact that it's deprecated is all the user needs to know.

    polespinasa commented at 7:09 PM on May 22, 2026:

    I am ok with both sentences, will not oppose, but I can imagine some software relaying on the Bitcoin Core RPC, ignoring the deprecation alert and then complaining because some option was removed without informing.

    Imho it is harmless to add a text mentioning when it will be removed if it will.

    stickies-v commented at 12:51 AM on May 23, 2026:

    Bitcoin Core does not have a roadmap, so we do not know if/when something will be removed until it gains sufficient consensus after it's been proposed. That's why I think it's not practical.

    polespinasa commented at 1:54 PM on May 25, 2026:

    There are times that we do know if it will. In those is when I think it is useful to indicate. An example #31278

    I am not saying to always indicate the intetion, because maybe that's unknown, but if it is known, is useful for users to know when that option will stop being available.

  31. in doc/developer-notes.md:1378 in bd3ad347b9 
    1373 | +
1374 | +- To deprecate an entire RPC method, gate the old behavior behind `-deprecatedrpc=<feature>`.
1375 | +- The RPC help text must mention the deprecation, the intention of removal, and the
1376 | +  `-deprecatedrpc=<feature>` flag that re-enables it during the grace period.
1377 | +  See [example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc/src/rpc/blockchain.cpp#L1316-L1323)
1378 | +  and [#31278](https://github.com/bitcoin/bitcoin/pull/31278) as a worked example.
    stickies-v commented at 1:53 PM on May 22, 2026:

    Just a single inlined example here would be more helpful

  32. in doc/developer-notes.md:1395 in bd3ad347b9 
    1390 | +  with the version they were deprecated and, if planned, the intended removal version.
1391 | +
1392 | +### ZMQ
1393 | +
1394 | +- Deprecated ZMQ topics or behaviors should be documented in `doc/zmq.md` with the version
1395 | +  they were deprecated and, if planned, the intended removal version.
    stickies-v commented at 1:56 PM on May 22, 2026:

    Would leave out the intended removal version here too, it's not practical.

  33. stickies-v commented at 1:57 PM on May 22, 2026: contributor

    Concept ACK

  34. 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
    2e9fdcc6da
  35. fernandguil force-pushed on May 22, 2026
  36. fernandguil commented at 7:31 PM on May 22, 2026: contributor

    Thanks for the context @polespinasa — I'll keep it as is per @stickies-v's suggestion, but I understand the reasoning for including it. Happy to revisit if there's consensus to add it back.

  37. fernandguil commented at 1:01 AM on May 23, 2026: contributor

    Makes sense, thanks for the clarification @stickies-v — agreed that without a roadmap it's better to avoid committing to timelines in the docs. The current text already omits any mention of removal timing.

  38. fernandguil commented at 5:36 PM on May 25, 2026: contributor

    Both points make sense to me. @polespinasa @stickies-v — happy to update the text either way once you two reach consensus. Just let me know what you'd like.

  39. fernandguil requested review from polespinasa on May 26, 2026
  40. fernandguil requested review from stickies-v on May 26, 2026
  41. maflcko commented at 6:15 AM on May 26, 2026: member

    lgtm ACK 2e9fdcc6da69238abbb1811a04c2beb6dba3b24a

  42. polespinasa commented at 6:18 AM on May 26, 2026: member

    ACK 2e9fdcc6da69238abbb1811a04c2beb6dba3b24a

    My comment is just a nit, as said non-blocking :)

  43. stickies-v commented at 10:23 AM on May 26, 2026: contributor

    ACK 2e9fdcc6da69238abbb1811a04c2beb6dba3b24a

  44. sedited approved
  45. sedited commented at 1:11 PM on May 26, 2026: contributor

    ACK 2e9fdcc6da69238abbb1811a04c2beb6dba3b24a

  46. sedited merged this on May 26, 2026
  47. sedited closed this on May 26, 2026
Contributors
fernandguilDrahtBotmaflckopolespinasastickies-vsedited


polespinasastickies-v

Labels
Docs
Linked (view graph)
#31278 wallet, rpc: deprecate settxfee and paytxfee#31980 Doc: Feature deprecation and removal process documentation.
github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-05-31 17:51 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me