DOC: clarify the experimental status for certain features

Certain features require "expose-experimental-directives" to be set in
the global section. Let's clarify that experimental featuers are only
maintained in best effort mode, may break during the stable cycle, and
are generally not maintained beyond the release of the next LTS branch
since it is extremely challenging, and early adopters are expected to
upgrade to benefit from improvements anyway.

diff --git a/BRANCHES b/BRANCHES
index 53b2ee99619672cf904711afd7b6524c49341b6e..cc2c15f6e0f35b6ba3805ea08a058587e0b3260f 100644 (file)
--- a/BRANCHES
+++ b/BRANCHES
@@ -171,7 +171,17 @@ feedback for developers:
     as the previous releases that had 6 months to stabilize. In terms of
     stability it really means that the point zero version already accumulated
     6 months of fixes and that it is much safer to use even just after it is
-    released.
+    released. There is one exception though, features marked as "experimental"
+    are not guaranteed to be maintained beyond the release of the next LTS
+    branch. The rationale here is that the experimental status is made to
+    expose an early preview of a feature, that is often incomplete, not always
+    in its definitive form regarding configuration, and for which developers
+    are seeking feedback from the users. It is even possible that changes will
+    be brought within the stable branch and it may happen that the feature
+    breaks. It is not imaginable to always be able to backport bug fixes too
+    far in this context since the code and configuration may change quite a
+    bit. Users who want to try experimental features are expected to upgrade
+    quickly to benefit from the improvements made to that feature.
 
   - for developers, given that the odd versions are solely used by highly
     skilled users, it's easier to get advanced traces and captures, and there

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 14b2e8812489bcc5412e4022fefed7ba4261211b..8aec5faae65fb608ebc917d5e1be0204248d48f1 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -2457,7 +2457,14 @@ expose-deprecated-directives
 
 expose-experimental-directives
   This statement must appear before using directives tagged as experimental or
-  the config file will be rejected.
+  the config file will be rejected. Please note that features covered by this
+  option are not guaranteed to work well and may break during the maintenance
+  cycle. Developers will maintain them in best effort mode while the next
+  version is being worked on, and will deploy any reasonable effort to avoid
+  breaking them but with no guarantee. For these reasons, these features are
+  not expected to be supported beyond the release of the next LTS release.
+  Users who want to try experimental features are expected to upgrade quickly
+  to benefit from the improvements made to that feature.
 
 external-check [preserve-env]
   Allows the use of an external agent to perform health checks. This is