MINOR: doc: elaborate on diagnostic mode behavior

Commit 7b01a8dbdd("MINOR: global: define diagnostic mode of execution")
in 2.4-dev15 introduced diagnostic mode for config warnings.

It was initially designed to be ignored by "zero-warning" mode
(-dW) and documented accordingly.

Since commit ced4148401 ("BUG/MINOR: diag: always show the version
before dumping a diag warning") in 3.0-dev3 this changed, and
zero-warning mode combined with diagnostic messages stop haproxy from
starting. This appears to be a unintended consequence in ced4148401.

Since commit 7d63efa5f5 ("MINOR: errors: add ha_diag_notice() to
report diag-level notifications") there is a distinction between
what should not interact with zero-warning mode (ha_diag_notice()),
and the previous behavior with ha_diag_warning().

Explain the that some diagnostic message interact with zero-warning
and that diagnostic message will be backported, as such diagnostic
mode must only be used interactively.

Should be backported to stable trees.

Co-Authored-By: Willy Tarreau <w@1wt.eu>

diff --git a/doc/management.txt b/doc/management.txt
index 6bfeec6ca0da5517c7a2b4684813bf6d37a7edfc..c314537df3e2f9ff465c3cfdc21de23ff720360e 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -237,8 +237,18 @@ list of options is :
     key. Please also see the CLI's "set anon" command.
 
   -dD : enable diagnostic mode. This mode will output extra warnings about
-    suspicious configuration statements. This will never prevent startup even in
-    "zero-warning" mode nor change the exit status code.
+    suspicious configuration statements. Some outputs will prevent startup
+    in "zero-warning" mode.
+
+    Please note that such diagnostics are essentially meant to raise
+    awareness of humans about some potential latent problems which might
+    be totally intentional, and are subject to change including within a
+    stable branch as well as between machines running the exact same
+    configurations. As such they *will* regularly report valid statements
+    as suspicious, and should only be used combined with "-c" to perform
+    a more in-depth diagnostic. Their result should never be used to
+    prevent a service from starting (what happens when combined with
+    "zero-warning" or "-dW").
 
   -dF : disable data fast-forward. It is a mechanism to optimize the data
     forwarding by passing data directly from a side to the other one without