mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-22 22:45:27 +01:00
Code Issues Projects Releases Wiki Activity
core-lightning/doc/developers-guide/deprecations.md

60 lines
8.5 KiB
Markdown
Raw Normal View History

doc: start a list of current deprecations. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-01-25 10:58:54 +10:30
---
title: "Deprecated Feature"
slug: "deprecations"
excerpt: "Deprecated features and timeline for old feature removals."
hidden: false
---
lightningd: mark all internal deprecations by version. I did some CHANGELOG and git digging to see when these were deprecated, and some were very old (v0.8.2!). But since they didn't warn users loudly, I chose to do so this release only. I renamed ld's `deprecated_apis` to `deprecated_ok` to make sure I caught them all. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-01-25 10:58:55 +10:30
| Name | Type | First Deprecated | Last Supported | Description |
|--------------------------------------|--------------------|------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| listconfigs.configlist | Fields | v23.08 | v24.08 | Instead of direct members with names equal the config variable, there's now a `configs` sub-object containing a member with details of each config setting |
| connection_notification.rawfields | Notification Field | v23.08 | v24.08 | All notifications now wrap members in an object of the same name |
| disconnection_notification.rawfields | Notification Field | v23.08 | v24.08 | All notifications now wrap members in an object of the same name |
| block_added_notification.block | Notification Field | v23.08 | v24.08 | All notifications now wrap members in an object of the same name |
| accept-htlc-tlv-types | Config | v23.08 | v24.08 | New `accept-htlc-tlv-type` can be specified multiple times, which is cleaner |
| bind-addr.torv3 | Config | v23.08 | v24.08 | `announce-addr` makes more sense for Tor addresses |
| addr.torv3 | Config | v23.08 | v24.08 | `announce-addr` makes more sense for Tor addresses |
| addr.socket | Config | v23.08 | v24.08 | `bind-addr` makes more sense for local sockets since we cannot announce them |
| announce-addr-dns | Config | v23.08 | v24.08 | Use `bind-addr=dns:` to specify DNS announcements on a per-address basis |
| rest-port.clnrest-prefix | Config | v23.11 | v24.11 | Autodetect where we need to rename `rest-port` to `clnrest-port` (added in v23.11) |
| rest-protocol.clnrest-prefix | Config | v23.11 | v24.11 | Autodetect where we need to rename `rest-protocol` to `clnrest-protocol` (added in v23.11) |
| rest-host.clnrest-prefix | Config | v23.11 | v24.11 | Autodetect where we need to rename `rest-host` to `clnrest-host` (added in v23.11) |
| rest-certs.clnrest-prefix | Config | v23.11 | v24.11 | Autodetect where we need to rename `rest-certs` to `clnrest-certs` (added in v23.11) |
| ....0-or-1 | Config | v23.08 | v24.08 | Boolean options (in plugins only) used to accept `0` or `1` in place of `true` or `false` |
| options.flag.default-not-false | Getmanifest Reply | v23.08 | v24.08 | `flag` options with a default which is not `false` (would be meaningless, since user can only set it to `true` |
| plugin.nonumericids | Getmanifest Reply | v23.08 | v24.08 | Plugins must specify that they can accept non-numeric command ids (numeric ids are deprecated) |
plugins/bcli: use per-command deprecation flags. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-01-25 10:58:56 +10:30
| listchannels.include_private | Field(s) | v24.02 | v24.08 | `listchannels` including private channels (now use listpeerchannels which gives far more detail) |
BOLT: update to include 2016 for max_htlc_cltv. And deprecate the --max-locktime-blocks which allows them to set it. Hilariously, the spec misspells CLTV as CTLV at one point, so we work around it for now. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-03-18 14:37:02 +10:30
| max-locktime-blocks | Config | v24.05 | v24.11 | --max-locktime-blocks is now set to 2016 in the BOLT 4 spec |
commando: update removal version for rpcs We documented them as deprecated in v23.08 but unintentionally didn't deprecate them in the code. Thus we are starting their actual deprecation cycle from v24.08 release. Updating removal version for commands `commando-rune`, `commando-listrunes`, and `commando-blacklist` Changelog-None.
2024-06-14 11:05:52 -07:00
| commando-rune | Command | v23.08 | v25.02 | replaced with `lightning-createrune` |
| commando-listrunes | Command | v23.08 | v25.02 | replaced with `lightning-showrunes` |
| commando-blacklist | Command | v23.08 | v25.02 | replaced with `lightning-blacklistrune` |
common: BOLT update: option_anchors_zero_fee_htlc_tx is now simply "option_anchors". This is a difficult transition for us: this string appears in channel types. We make the transition now in the understanding that it will be more difficult in future. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Deprecated: JSON-RPC: `listpeers` `features` array string "option_anchors_zero_fee_htlc_tx": use "option_anchors" (spec renamed it). Changelog-Added: JSON-RPC: `listpeers` `features` array string uses "option_anchors" for feature 22/23, following renaming in BOLT 9. Changelog-Changed: JSON-RPC: `listclosedchannels`, `listpeerchannels`, `openchannel_update`, `openchannel_init`, `fundchannel`, `fundchannel_start` and `multifundchannel`: `channel_type` array `names` now contains "anchors" instead of "anchors_zero_fee_htlc_tx". Changelog-Changed: lightningd: `--list-features-only` now lists "option_anchors" instead of "option_anchors_zero_fee_htlc_tx".
2024-06-19 10:06:35 +09:30
| listpeers.features.option_anchors_zero_fee_htlc_tx | Field | v24.08 | v25.08 | Renamed to `option_anchors` in the spec: check for that in `features` instead |
config: actually deprecate --experimental-anchors. Document and enforce the --experimental-anchors deprecation, which was somehow missed in v24.02 Changelog-Deprecated: Config: the --experimental-anchors option is ignored (on by default since v24.02).
2024-07-09 18:13:44 +09:30
| experimental-anchors | Config | v24.02 | v25.02 | Now the default |
config: onion messages are now always enabled. Changelog-Added: Protocol: onion messages are now supported by default. Changelog-Deprecated: Config: the --experimental-onion-messages option is ignored (on by default).
2024-07-10 12:27:25 +09:30
| experimental-onion-messages | Config | v24.08 | v25.02 | Now the default |
commando: use deprecation API for missing ids. In this case we don't have a matching "command", so we need a special API. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-01-25 10:58:56 +10:30
doc: start a list of current deprecations. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-01-25 10:58:54 +10:30
Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.
Types of deprecation:
* Command: an entire command is removed. Usually replaced by a more generic or better-named one.
* Config: a commandline/configuration option is removed. Usually made the default, or replaced by generalized or better-named.
* Field(s): a JSON field output. We cannot detect if you are using these, of course.
* Parameter(s): a JSON RPC input.
* Getmanifest Reply: a field in the JSON reply which plugins give to `getmanifest`.
* Hook Return: a field/value in the JSON reply which plugins give to a plugin hook.
* Notification Field: a field in the JSON notification to a plugin.
For each deprecation:
1. The deprecation is listed here, and in the CHANGELOG.md file.
2. We try to give at least 2 versions before removal.
3. Then one version where we issue a warning message if we detect a deprecated feature being used (not possible for deprecatred `Field` types).
4. At least one version where the deprecated feature can be explicit re-enabled using `i-promise-to-fix-broken-api-user=FEATURENAME`.
This is designed to minimize the chance that anyone will be surprised by a change!
You can also test earlier. Deprecated features can be disabled in three ways:
1. `developer` mode changes the default deprecations to disabled globally.
2. `allow-deprecated-apis=` lets you disable (`false`) or re-enable (`true`) globally.
3. The `deprecations` JSON API can disable/re-enable deprecations for a specific client (added in *v24.02*).
Reference in a new issue Copy permalink