[master] 5e3f752d3 changes: First pass for 7.2.0

[Dridi Boukelmoune]

commit 5e3f752d3fe223324a317d1c912d388ef4eb73a9
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Mon Sep 5 16:16:54 2022 +0200

    changes: First pass for 7.2.0

diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index fbda9d6b9..cc4b2ea61 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -20,54 +20,137 @@ merged, may be found in the `change log`_.
 varnishd
 ========
 
+Extensions
+~~~~~~~~~~
+
+TODO: VEXT
+
 Parameters
 ~~~~~~~~~~
 
-**XXX changes in -p parameters**
+Duration values (with a unit in seconds) can optionally take a duration
+unit with the same syntax as VCL. For example, the default values of
+``default_ttl``, ``default_grace`` and ``default_keep`` were changed
+respectively from ``120.000``, ``10.000`` and ``0.000`` to ``2m``, ``10s``
+and ``0s``.
+
+The platform-dependent ``tcp_keepalive_time`` parameter is supported on
+MacOS.
+
+The new ``vcc_feature`` bits parameter replaces previous ``vcc_*`` boolean
+parameters. The latter still exist as deprecated aliases.
 
 Other changes in varnishd
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The VCC (compilation) process no longer loads VMODs using ``dlopen(3)`` to
+collect their metadata.
+
+Background fetch tasks are no longer queued as this could result in slow
+grace hits subject to indefinite delays when thread pools are saturated.
+
 Changes to VCL
 ==============
 
 VCL variables
 ~~~~~~~~~~~~~
 
-**XXX new, deprecated or removed variables, or changed semantics**
+ESI sub-requests can no longer inherit a ``req.http.transfer-encoding``
+header since the request body is strictly handled by the top request.
 
-Other changes to VCL
-~~~~~~~~~~~~~~~~~~~~
+The ``resp.http.via`` header generated by Varnish uses ``server.identity``
+which defaults to the host name. A ``req.http.via`` header is generated
+also before entering ``vcl_recv``. If a client request or backend response
+already had a Via header, it is now appended to instead of overwritten.
+
+The ``server.identity`` variable is guaranteed to be a single token as
+defined in the HTTP grammar, to safely be used as either a host name or
+pseudonym in Via headers.
+
+The ``now`` variable remains constant in a VCL subroutine. This was already
+the case, but is now (pun intended) formally defined behavior. It keeps the
+same value even if the execution blocks for a significant time, for example
+while calling a VMOD function.
 
 VMODs
 =====
 
-**XXX changes in the bundled VMODs**
+For a real time timestamp, the function ``std.now()`` can be used instead.
+There is also a new ``std.timed_call()`` to measure the execution time of a
+subroutine.
+
+Cookie headers generated by vmod_cookie no longer have a spurious trailing
+semi-colon (``';'``) at the end of the string.
 
 varnishlog
 ==========
 
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
+The ``Begin`` log records may contain a 4th field with the sub-level of
+sub-tasks. The ``Begin[4]`` field is used by the ``-E`` option (or lack
+thereof) in log utilities to include sub-tasks or not. Internally, only ESI
+tasks are subject to this filtering, but it can apply to tasks spawned by
+VMODs too.
 
-varnishadm
-==========
+.. XXX: any reason against ``varnish{hist,top} -k``?
 
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
+The ``-k`` option from ``varnishlog`` is now available in ``varnishncsa``.
 
 varnishstat
 ===========
 
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
+The unused counter ``MAIN.fetch_no_thread`` was repurposed and renamed to
+``MAIN.bgfetch_no_thread`` to signal when background fetch tasks fail to
+be scheduled because thread pools are saturated.
+
+To help estimate the rate of ``vsl_space`` consumption, the new counter
+``MAIN.shm_bytes`` was added. It offers a finer-grained metric than the
+existing ``MAIN.shm_cycles`` that depends on the ``vsl_space`` setting.
+
+A new contribution script called ``varnishstatdiff`` can be used to compare
+the output of two ``varnishstat -1`` executions with a friendly diff format
+for ``varnishstat``'s specific output.
 
 varnishtest
 ===========
 
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
+New macros ``${pkg_version}`` and ``${pkg_branch}`` expanding respectively
+to ``7.2.0`` and ``7.2`` for the current release.
+
+It is possible to match the text on screen against a regular expression
+with the new ``process -match`` command.
+
+The new ``filewrite [-a]`` command can put or append text into a file.
+
+A Varnish instance name in a VTC is used by default as the server identity
+for predictable Via headers.
+
+For example::
+
+    varnish v1 -vcl+backend { ... }
+
+The expected Via header is::
+
+    Via: 1.1 v1 (Varnish/7.2)
+
+The instance name can still be set to a different value using the ``-arg``
+command to change the ``varnishd -i`` option.
 
 Changes for developers and VMOD authors
 =======================================
 
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
+The ``varnishtest -i`` option only works from a Varnish source tree, in
+which case the new macro ``${topsrc}`` is available in addition to the
+old ``${topbuild}`` macro.
+
+The functions ``VRT_AddVDP()``, ``VRT_AddVFP()``, ``VRT_RemoveVDP()`` and
+``VRT_RemoveVFP()`` are deprecated.
+
+The ``VCS_String()`` function can take the string ``"B"`` for the package
+branch.
+
+The ``vnum.h`` functions are exposed to VMOD and VEXT authors.
+
+The termination rules for ``WRK_BgThread()`` were relaxed to allow VMODs to
+use it.
 
 *eof*