From e7c8deb81017c829439a4511a1dcb70fb8202915 Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Fri, 17 Oct 2025 18:39:03 +0200 Subject: [PATCH] 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. --- BRANCHES | 12 +++++++++++- doc/configuration.txt | 9 ++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/BRANCHES b/BRANCHES index 53b2ee996..cc2c15f6e 100644 --- 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 14b2e8812..8aec5faae 100644 --- 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