[master] 2339adbfb Release documentation

[Nils Goroll]

commit 2339adbfbba532ead6182b956f7748025f593d97
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Sep 14 20:02:21 2023 +0200

    Release documentation

diff --git a/doc/changes.rst b/doc/changes.rst
index 1d630bffb..9b09a3513 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -145,7 +145,7 @@ Varnish Cache NEXT (2023-09-15)
   ``/usr/share/varnish/vcc`` (or equivalent) to enable re-use by other
   tools like code editors.
 
-* The :ref:`vcl-step(7)` manual page has been added to document the
+* The :ref:`vcl-steps(7)` manual page has been added to document the
   VCL state machines.
 
 * ``HSH_Cancel()`` has been moved to ``VDP_Close()`` to enable
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 2070fadd5..7ef34f41e 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -16,54 +16,114 @@ merged, may be found in the `change log`_.
 varnishd
 ========
 
-Parameters
-~~~~~~~~~~
+HTTP/2 header field validation is now more strict with respect to
+allowed characters.
 
-**XXX changes in -p parameters**
+The :ref:`vcl-steps(7)` manual page has been added to document the VCL
+state machines.
 
-Other changes in varnishd
-~~~~~~~~~~~~~~~~~~~~~~~~~
+VCL Tracing
+~~~~~~~~~~~
 
-Changes to VCL
-==============
+VCL tracing now needs to be explicitly activated by setting the
+``req.trace`` or ``bereq.trace`` VCL variables, which are initialized
+from the ``feature +trace`` flag. Only if the trace variables are set
+will ``VCL_trace`` log records be generated.
+
+Consequently, ``VCL_trace`` has been removed from the default
+``vsl_mask``, so any trace records will be emitted by
+default. ``vsl_mask`` can still be used to filter ``VCL_trace``
+records.
 
-VCL variables
-~~~~~~~~~~~~~
+To trace ``vcl_init {}`` and ``vcl_fini {}``, set the ``feature
++trace`` flag while the vcl is loaded/discarded.
 
-**XXX new, deprecated or removed variables, or changed semantics**
+Parameters
+~~~~~~~~~~
 
-Other changes to VCL
-~~~~~~~~~~~~~~~~~~~~
+The ``startup_timeout`` parameter now specifically replaces
+``cli_timeout`` for the initial startup only.
 
-VMODs
-=====
+Changes to VCL
+==============
 
-**XXX changes in the bundled VMODs**
+The ``Content-Length`` and ``Transfer-Encoding`` headers are now
+protected. For the common use case of ``unset
+(be)req.http.Content-Length`` to dismiss a body, ``unset
+(be)req.body`` should be used.
 
 varnishlog
 ==========
 
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
+Object creation failures by the selected storage engine are now logged
+under the ``Error`` tag as ``Failed to create object object from %s
+%s``.
 
 varnishadm
 ==========
 
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
+Tabulation of the ``vcl.list`` CLI output has been modified slightly.
 
 varnishstat
 ===========
 
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
+The counter ``MAIN.http1_iovs_flush`` has been added to track the
+number of premature ``writev()`` calls due to an insufficient number
+of IO vectors. This number is configured through the ``http1_iovs``
+parameter for client connections and implicitly defined by the amount
+of free workspace for backend connections.
 
 varnishtest
 ===========
 
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
+The basename of the test directory is now available as the ``vtcid``
+macro to serve as a unique string across concurrently running tests.
+
+The ``varnishd_args_prepend`` and ``varnishd_args_append`` macros have
+been added to allow addition of arguments to ``varnishd`` invocations
+before and after those added by ``varnishtest`` by default.
+
+``User-Agent`` request and ``Server`` response headers are now created
+by default, containing the respective client and server name. The
+``txreq -nouseragent`` and ``txresp -noserver`` options disable
+addition of these headers.
 
 Changes for developers and VMOD authors
 =======================================
 
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
+Call sites of VMOD functions and methods can now be restricted to
+built-in subroutines using the ``$Restrict`` stanza in the VCC file.
+
+``.vcc`` files of VMODs are now installed to
+``/usr/share/varnish/vcc`` (or equivalent) to enable re-use by other
+tools like code editors.
+
+API Changes
+~~~~~~~~~~~
+
+The ``varnishapi`` version has been increased to 3.1 and the
+``VSHA256_*``, ``VENC_Encode_Base64()`` and ``VENC_Decode_Base64()``
+functions are now exposed.
+
+In ``struct vsmwseg`` and ``struct vsm_fantom``, the ``class`` member
+has been renamed to ``category``.
+
+The ``VSB_quote_pfx()`` (and, consequently, ``VSB_quote()``) function
+no longer produces ``\v`` for a vertical tab. This improves
+compatibility with JSON.
+
+Additions to varnish C header files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``PTOK()`` macro has been added to ``vas.h`` to simplify error
+checking of ``pthread_*`` POSIX functions.
+
+The ``v_cold`` macro has been added to add ``__attribute__((cold))``
+on compilers supporting it. It is used for ``VRT_fail()`` to mark
+failure code paths as cold.
+
+The utility macros ``ALLOC_OBJ_EXTRA()`` and ``ALLOC_FLEX_OBJ()`` have
+been added to ``miniobj.h`` to simplify allocation of objects larger
+than a struct and such with a flexible array.
 
 *eof*
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..f04a2d933 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -8,26 +8,27 @@ released versions of Varnish, see:** :ref:`whats-new-index`
 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:**
+Important VCL Changes
+=====================
 
-* Elements of VCL that have been removed or are deprecated, or whose
-  semantics have changed.
+When upgrading from Varnish-Cache 7.3, there is only one breaking
+change to consider in VCL:
 
-* -p parameters that have been removed or are deprecated, or whose
-  semantics have changed.
+The ``Content-Length`` and ``Transfer-Encoding`` headers are now
+*protected*, they can neither be changed nor unset. This change was
+implemented to avoid de-sync issues from accidental, inadequate
+modifications of these headers.
 
-* Changes in the CLI.
+For the common use case of ``unset (be)req.http.Content-Length`` to
+dismiss a request body, ``unset (be)req.body`` should be used.
 
-* Changes in the output or interpretation of stats or the log, including
-  changes affecting varnishncsa/-hist/-top.
+Parameter Changes
+=================
 
-* Changes that may be necessary in VTCs or in the use of varnishtest.
-
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
-  clients.
+The new ``varnishd`` parameter ``startup_timeout`` now specifically
+replaces ``cli_timeout`` for the initial startup only. In cases where
+``cli_timeout`` was increased specifically to accommodate long startup
+times (e.g. for storage engine initialization), ``startup_timeout``
+should be used.
 
 *eof*