mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-01-19 05:44:12 +01:00
Code Issues Projects Releases Wiki Activity

doc: start a list of current deprecations.

Browse Source 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2024-01-25 10:58:54 +10:30
parent d051a1ee67
commit a46f62bf06
1 changed files with 34 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/developers-guide/deprecations.md Normal file
View File

@ -0,0 +1,34 @@
---
title: "Deprecated Feature"
slug: "deprecations"
excerpt: "Deprecated features and timeline for old feature removals."
hidden: false
---
| Name | Type | First Deprecated | Last Supported | Description |
|-----------|-------|------------------|----------------|-------------|
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*).