<p>All software projects wrestle with deprecation trade-offs and these aren't necessarily specific to Bitcoin Core or Bitcoin projects (although Bitcoin Core would be considered on the more conservative side) or indeed the software industry generally.</p>
<p>Deprecating a feature has the upsides of reducing maintenance burden, shrinking the size of the codebase, reducing the test suite runtime and in some cases simplifying the user experience (e.g. if there are multiple features with overlapping functionality it can be difficult for the user to understand which feature to use).</p>
<p>The downsides of deprecating a feature are that it can potentially hurt the user experience and can break downstream projects with a reliance on that feature. As we are dealing with open source money in the worst cases this could mean users of those downstream projects lose money (though generally we are talking about stopping things from working rather than posing any particular risk to fund safety). Of course a deprecation could be botched too but implementation risk comes with any change, whether that be an added feature or a deleted feature.</p>
<p>These downsides can be mitigated to a material extent by staggered deprecations over multiple versions (warning log messages before full deprecation), release notes that highlight future intended deprecation and wider communication (e.g. mailing lists) that a certain feature is intended to be deprecated. Of course this does not guarantee that a user or downstream project reads of the planned deprecation but any project should at least plan to read the release notes of upstream projects that present a dependency. With awareness and with sufficient time to tweak their software ahead of time they should be able to avoid any negative impact on their users. It obviously requires developer hours to work around the deprecation.</p>
<p>Bitcoin Core is especially unique in that it eschews a BDFL (benevolent dictator for life) governance model (or indeed any model with an ultimate authority) and hence other than reviewed documentation there is no one individual to authoritatively say what its current approach to deprecation is.</p>
<p>In the past there have been a large number of deprecations across various areas (RPC inputs, entire RPCs, config options etc) and the number of deprecations does seem to have reduced over time as the project has matured and an increasing number of users and downstream projects have come to rely on it. However if Core were to stop doing any deprecations at all this would mean an ever increasing maintenance burden, ever expanding codebase/test suite and a user experience that could never be simplified. In the extreme these present security risks by themselves as contributor and maintainer time is allocated to things that should have been deprecated rather than more important things.</p>
<p>On a case by case basis it does seem Core will still allow deprecations in certain circumstances but only when they are assessed to be worth the cost when it comes to both communication requirements and downstream project risk.</p>
<p>There is a <code>-deprecatedrpc=X</code> option that lets you bring back a deprecated RPC temporarily (for RPCs that haven't had their code entirely deleted) but there isn't the equivalent for configuration options at the time of writing. (More details on RPC versioning are <a href="https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md#versioning" rel="nofollow noreferrer">here</a>.)</p>
<p>At the time of writing there are PRs/issues open that intend to deprecate the <a href="https://github.com/bitcoin/bitcoin/issues/20160" rel="nofollow noreferrer">legacy wallet</a>, <a href="https://github.com/bitcoin/bitcoin/pull/22644" rel="nofollow noreferrer">UPnP support for older versions</a>, the <a href="https://github.com/bitcoin/bitcoin/issues/23259" rel="nofollow noreferrer">REST API</a> etc. Just being open does not mean they will necessarily be merged and included in a release.</p>
<p>Here are some additional thoughts (<a href="https://github.com/bitcoin/bitcoin/pull/24606#issuecomment-1076377877" rel="nofollow noreferrer">1</a>, <a href="https://github.com/bitcoin/bitcoin/pull/24606#issuecomment-1076349358" rel="nofollow noreferrer">2</a>, <a href="https://github.com/bitcoin/bitcoin/issues/24638#issuecomment-1075233330" rel="nofollow noreferrer">3</a>) from Core contributors:</p>
<blockquote>
<p>RPC result fields (and sometimes input params) are still deprecated and a config option may possibly be removed (having a deprecation process for this may be an improvement). Removing an RPC outright seems much more rare to avoid needlessly breaking the API / user space, and sometimes an RPC is made hidden (not returned in the CLI help) but not removed. (Jon Atack)</p>
</blockquote>
<blockquote>
<p>If there is any user using this with a valid use case in mind, we shouldn't remove it nor deprecate it. (Marco Falke)</p>
</blockquote>
<blockquote>
<p>I am not a fan of deprecating features because there is another way to achieve something. This will put frustration and mental burden on our users, so there should be a convincing motivation for the deprecation. (Marco Falke)</p>
</blockquote>

CC BY-SA 4.0
2022-03-24T18:14:10.557Z
2022-03-25T10:30:35.723Z
2022-03-25T10:30:35.723Z
Michael Folkson
<p>What are the considerations when assessing whether it is appropriate to deprecate a feature in Bitcoin Core? What has the approach been in the past towards deprecation? Has this changed in recent times? Is there a process today to follow when deprecation is considered to be appropriate?</p>

<bitcoin-core><bitcoin-core-development>
What are the considerations when assessing whether to deprecate a feature in Bitcoin Core?
Michael Folkson
# What are the considerations when assessing whether to deprecate a feature in Bitcoin Core?

(Asked by: username_0 on 2022-03-24)

What are the considerations when assessing whether it is appropriate to deprecate a feature in Bitcoin Core? What has the approach been in the past towards deprecation? Has this changed in recent times? Is there a process today to follow when deprecation is considered to be appropriate?

**Tags:** bitcoin-core, bitcoin-core-development


---

## 1 answers

### Answer by username_0 on 2022-03-24. Score: 0 | Accepted answer

All software projects wrestle with deprecation trade-offs and these aren't necessarily specific to Bitcoin Core or Bitcoin projects (although Bitcoin Core would be considered on the more conservative side) or indeed the software industry generally.

Deprecating a feature has the upsides of reducing maintenance burden, shrinking the size of the codebase, reducing the test suite runtime and in some cases simplifying the user experience (e.g. if there are multiple features with overlapping functionality it can be difficult for the user to understand which feature to use).

The downsides of deprecating a feature are that it can potentially hurt the user experience and can break downstream projects with a reliance on that feature. As we are dealing with open source money in the worst cases this could mean users of those downstream projects lose money (though generally we are talking about stopping things from working rather than posing any particular risk to fund safety). Of course a deprecation could be botched too but implementation risk comes with any change, whether that be an added feature or a deleted feature.

These downsides can be mitigated to a material extent by staggered deprecations over multiple versions (warning log messages before full deprecation), release notes that highlight future intended deprecation and wider communication (e.g. mailing lists) that a certain feature is intended to be deprecated. Of course this does not guarantee that a user or downstream project reads of the planned deprecation but any project should at least plan to read the release notes of upstream projects that present a dependency. With awareness and with sufficient time to tweak their software ahead of time they should be able to avoid any negative impact on their users. It obviously requires developer hours to work around the deprecation.

Bitcoin Core is especially unique in that it eschews a BDFL (benevolent dictator for life) governance model (or indeed any model with an ultimate authority) and hence other than reviewed documentation there is no one individual to authoritatively say what its current approach to deprecation is.

In the past there have been a large number of deprecations across various areas (RPC inputs, entire RPCs, config options etc) and the number of deprecations does seem to have reduced over time as the project has matured and an increasing number of users and downstream projects have come to rely on it. However if Core were to stop doing any deprecations at all this would mean an ever increasing maintenance burden, ever expanding codebase/test suite and a user experience that could never be simplified. In the extreme these present security risks by themselves as contributor and maintainer time is allocated to things that should have been deprecated rather than more important things.

On a case by case basis it does seem Core will still allow deprecations in certain circumstances but only when they are assessed to be worth the cost when it comes to both communication requirements and downstream project risk.

There is a `-deprecatedrpc=X` option that lets you bring back a deprecated RPC temporarily (for RPCs that haven't had their code entirely deleted) but there isn't the equivalent for configuration options at the time of writing. (More details on RPC versioning are [here](https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md#versioning).)

At the time of writing there are PRs/issues open that intend to deprecate the [legacy wallet](https://github.com/bitcoin/bitcoin/issues/20160), [UPnP support for older versions](https://github.com/bitcoin/bitcoin/pull/22644), the [REST API](https://github.com/bitcoin/bitcoin/issues/23259) etc. Just being open does not mean they will necessarily be merged and included in a release.

Here are some additional thoughts ([1](https://github.com/bitcoin/bitcoin/pull/24606#issuecomment-1076377877), [2](https://github.com/bitcoin/bitcoin/pull/24606#issuecomment-1076349358), [3](https://github.com/bitcoin/bitcoin/issues/24638#issuecomment-1075233330)) from Core contributors:

> RPC result fields (and sometimes input params) are still deprecated and a config option may possibly be removed (having a deprecation process for this may be an improvement). Removing an RPC outright seems much more rare to avoid needlessly breaking the API / user space, and sometimes an RPC is made hidden (not returned in the CLI help) but not removed. (Jon Atack)

> If there is any user using this with a valid use case in mind, we shouldn't remove it nor deprecate it. (Marco Falke)

> I am not a fan of deprecating features because there is another way to achieve something. This will put frustration and mental burden on our users, so there should be a convincing motivation for the deprecation. (Marco Falke)


---

