[master] 342b706e8 director changes -> release notes, changes

[Nils Goroll]

commit 342b706e8691b4d8f3464099e0892753e8f9d4f8
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue Mar 5 13:04:15 2019 +0100

    director changes -> release notes, changes

diff --git a/doc/changes.rst b/doc/changes.rst
index 8d7d253e6..5e601b797 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -64,14 +64,12 @@ Varnish Cache trunk (ongoing)
   For best forward compatibility, we recommend that scripts parse JSON
   output as obtained using the ``-j`` option.
 
-* The format of the ``backend.list -j`` (JSON) cli command output has
-  changed:
+  See release notes for details.
 
-  * the ``probe_message`` field of a backend can now also have the
-    format ``[X, Y, state]``, X and Y being integers signifying X out
-    of Y probes/backends/...
+* The format of the ``backend.list -j`` (JSON) cli command output has
+  changed.
 
-.. expecting more changes here #2896
+  See release notes for details.
 
 * The undocumented ``-v`` option to the ``backend.list`` cli command
   has been removed
@@ -197,6 +195,12 @@ C APIs (for vmod and utility authors)
 
       AZ(ObjGetU64(req->wrk, req->body_oc, OA_LEN, &u));
 
+  * ``VRT_SetHealth()`` has been removed and ``VRT_SetChanged()``
+    added. ``VRT_LookupDirector()`` (only to be called from CLI
+    contexts) as been added.
+
+    See release notes for details
+
 * vmodtool has been changed significantly to avoid various name
   clashes. Rather than using literal prefixes/suffixes, vmod authors
   should now (and might have to for making existing code continue to
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 050483955..3c43b22ad 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -166,27 +166,47 @@ default, see :ref:`varnish-cli(7)`.
 
 .. _whatsnew_changes_vcl_list_backend_list:
 
-Listing backends and VCLs
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Listing backends
+~~~~~~~~~~~~~~~~
+
+``backend.list`` has grown an additional column, the output has
+changed and fields are now of dynamic width:
+
+* The ``Admin`` column now accurately states ``probe`` only if a
+  backend has some means of dynamically determining health state.
+
+* The ``Probe`` column has been changed to display ``X/Y``, where:
+
+  * Integer ``X`` is the number of good probes in the most recent
+    window; or if the backend in question is a director, the number of
+    healthy backends accessed via the director or any other
+    director-specific metric.
+
+  * Integer ``Y`` is the window in which the threshold for overall
+    health of the backend is defined (from the ``.window`` field of a
+    probe, see :ref:`vcl(7)`); or in the case of a director, the total
+    number of backends accessed via the director or any other
+    director-specific metric.
 
-The "probe message" field in the output of ``backend.list`` (in the
-``probe_message`` field of JSON format, or the ``Probe`` column of
-non-JSON output) has been changed to display ``X/Y state``, where:
+  If there is no probe or the director does not provide details,
+  ``0/0`` is output.
 
-* Integer ``X`` is the number of good probes in the most recent
-  window; or if the backend in question is a director, the number of
-  healthy backends accessed via the director.
+* The ``Health`` column has been added to contain the dynamic (probe)
+  health state and the format has been unified to just ``healthy`` or
+  ``sick``.
 
-* Integer ``Y`` is the window in which the threshold for overall
-  health of the backend is defined (from the ``.window`` field of a
-  probe, see :ref:`vcl(7)`); or in the case of a director, the total
-  number of backends accessed via the director.
+  If there is no probe, ``Health`` is always given as
+  ``healthy``. Notice that the administrative health as shown in the
+  ``Admin`` column has precedence.
 
-* ``state`` is one of the strings ``"good"`` or ``"bad"``, for the
-  overall health of the backend or director.
+In the ``probe_message`` field of ``backend.list -j`` output, the
+``Probe`` and ``Health`` columns appears as the array ``[X, Y,
+health]``.
 
-In the ``probe_message`` field of ``backend.list -j`` output, this
-appears as the array ``[X, Y, state]``.
+See :ref:`varnish-cli(7)` for details.
+
+Listing VCLs
+~~~~~~~~~~~~
 
 The non-JSON output of ``vcl.list`` has been changed:
 
@@ -251,4 +271,21 @@ Changes for developers and VMOD authors
 Python tools that generate code now prefer python 3 over python 2,
 when availabale.
 
+Directors
+~~~~~~~~~
+
+The director API has been changed slightly: The most relevant design
+change is that the ``healthy`` callback now is the only means to
+determine a director's health state dynamically, the ``sick`` member
+of ``struct director`` has been removed. Consequently,
+``VRT_SetHealth()`` has been removed and ``VRT_SetChanged()`` added to
+update the last health state change time.
+
+Presence of the ``healthy`` callback now also signifies if the
+director is considered to have a *probe* with respect to the CLI.
+
+The signature of the ``list`` callback has been changed to reflect the
+retirement of the undocumented ``backend.list -v`` parameter and to
+add a ``VRT_CTX``.
+
 *eof*