[master] 2a84483ff whats-new: Add upgrade notes

[Dridi Boukelmoune]

commit 2a84483ffbfc48f11f28e05c453a29eb0e1f5e81
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Fri Mar 15 10:51:35 2024 +0100

    whats-new: Add upgrade notes

diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..706966391 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -1,33 +1,69 @@
-**Note: This is a working document for a future release, with running
-updates for changes in the development branch. For changes in the
-released versions of Varnish, see:** :ref:`whats-new-index`
-
 .. _whatsnew_upgrading_CURRENT:
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 Upgrading to Varnish **$NEXT_RELEASE**
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-**XXX: how to upgrade from previous deployments to this
-version. Limited to work that has to be done for an upgrade, new
-features are listed in "Changes". Explicitly mention what does *not*
-have to be changed, especially in VCL. May include, but is not limited
-to:**
+Logs
+====
+
+The optional reason field of ``BackendClose`` records changed from a
+description (for example "Receive timeout") to a reason tag (for example
+``RX_TIMEOUT``). This will break VSL queries based on the reason field.
+
+Using a tag should however make queries more reliable::
+
+    # before
+    varnishlog -q 'BackendClose ~ "Receive timeout"'
+
+    # after
+    varnishlog -q 'BackendClose[4] eq RX_TIMEOUT'
+
+Such queries would no longer break when a description is changed.
+
+Timeouts
+========
+
+The value zero for timeouts could mean either timing out immediately, never
+timing out, or not having a value and falling back to another. The semantic
+changed so zero always means non-blocking, timing out either immediately after
+checking whether progress is possible, or after a millisecond in parts where
+this can't practically be done in a non-blocking fashion.
+
+In order to disable a timeout, that is to say never time out, the value
+``INFINITY`` is used (or tested with ``isinf()``).
+
+In the places where a timeout setting may fall back to another value, like
+VCL variables falling back to parameters, ``NAN`` is used to convey the lack
+of timeout setting.
+
+VCL
+~~~
+
+All the timeouts backed by parameters can now be unset, meaning that setting
+the value zero no longer falls back to parameters.
+
+Parameters
+~~~~~~~~~~
 
-* Elements of VCL that have been removed or are deprecated, or whose
-  semantics have changed.
+All the timeout parameters that can be disabled are now documented with the
+``timeout`` flag, meaning that they can take the special value ``never`` for
+that purpose::
 
-* -p parameters that have been removed or are deprecated, or whose
-  semantics have changed.
+    varnishadm param.set pipe_timeout never
 
-* Changes in the CLI.
+VRT
+~~~
 
-* Changes in the output or interpretation of stats or the log, including
-  changes affecting varnishncsa/-hist/-top.
+For VMOD authors, it means that the ``vtim_dur`` type expects ``INFINITY`` to
+never time out or ``NAN`` to not set a timeout.
 
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+For VMOD authors managing backends, there is one exception where a timeout
+fallback did not change from zero to ``NAN`` in ``struct vrt_backend``. The
+``vtim_dur`` fields must take a negative value in order to fall back to the
+respective parameters due to a limitation in how VCL is compiled.
 
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
-  clients.
+As a convenience, a new macro ``VRT_BACKEND_INIT()`` behaves like ``INIT_OBJ``
+but initializes timeouts to a negative value.
 
 *eof*