From a46f62bf0636aee9ddd9b15978b3adb81538e8a6 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 25 Jan 2024 10:58:54 +1030 Subject: [PATCH] doc: start a list of current deprecations. Signed-off-by: Rusty Russell --- doc/developers-guide/deprecations.md | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 doc/developers-guide/deprecations.md diff --git a/doc/developers-guide/deprecations.md b/doc/developers-guide/deprecations.md new file mode 100644 index 000000000..f4c2e5812 --- /dev/null +++ b/doc/developers-guide/deprecations.md @@ -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*).