[master] e45e98d06 upgrading: First pass for the 7.2 release

[Dridi Boukelmoune]

commit e45e98d06922aaa2fe29ab7f9357312eb6e57ebb
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Wed Sep 7 17:20:05 2022 +0200

    upgrading: First pass for the 7.2 release

diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..1f46dd179 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -8,26 +8,95 @@ 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:**
+varnishd
+========
 
-* Elements of VCL that have been removed or are deprecated, or whose
-  semantics have changed.
+Parameters
+~~~~~~~~~~
 
-* -p parameters that have been removed or are deprecated, or whose
-  semantics have changed.
+The following parameters are deprecated:
 
-* Changes in the CLI.
+- ``vcc_allow_inline_c``
+- ``vcc_err_unref``
+- ``vcc_unsafe_path``
 
-* Changes in the output or interpretation of stats or the log, including
-  changes affecting varnishncsa/-hist/-top.
+They can still be set as individual boolean parameters. The deprecated
+aliases will be removed in a future release.
 
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+They are replaced by the ``vcc_feature`` bits parameter:
 
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
-  clients.
+- ``allow_inline_c``
+- ``err_unref`` (enabled by default)
+- ``unsafe_path`` (enabled by default)
+
+The following commands are equivalent::
+
+    param.set vcc_err_unref off
+    param.set vcc_feature -err_unref
+
+Identity
+~~~~~~~~
+
+The server identity must be a valid HTTP token, which may pose a problem
+to existing setups. For example ``varnishd -i "edge server 1"`` is no
+longer accepted. You can use something like ``varnishd -i "edge-server-1"``
+instead.
+
+VCL
+===
+
+Varnish generates a Via header and forwards it to the backend by default.
+This can be prevented for example in ``vcl_recv`` or ``vcl_backend_fetch``.
+
+::
+
+    sub vcl_recv {
+        unset req.http.via;
+    }
+
+    sub vcl_backend_fetch {
+        unset bereq.http.via;
+    }
+
+The Via header is generated with the ``server.identity`` variable for
+the ``received-by`` field. See `rfc9110_` for a description of the Via
+header.
+
+.. _rfc9110: https://www.rfc-editor.org/rfc/rfc9110#name-via
+
+VMODs
+=====
+
+Cookies generated by vmod_cookie used to have a trailing semi-colon that
+goes against the recommandations from `rfc6265`_. This should not pose a
+problem, unless a piece of VCL code or a backend have come to rely on this
+incorrect behavior.
+
+.. _rfc6265: https://www.rfc-editor.org/rfc/rfc6265
+
+varnishlog
+==========
+
+The ``Begin`` and ``Link`` log records have an optional 4th field for the
+sub-request level. This may break log processors, log queries or NCSA
+formats that expect those records to have exactly 3 fields.
+
+varnishstat
+===========
+
+The ``MAIN.fetch_no_thread`` counter is gone, it never worked. Track the
+``MAIN.bgfetch_no_thread`` counter instead.
+
+Changes for developers and VMOD authors
+=======================================
+
+The functions ``VRT_AddVDP()``, ``VRT_AddVFP()``, ``VRT_RemoveVDP()`` and
+``VRT_RemoveVFP()`` are deprecated. Use ``VRT_AddFilter()`` to add a pair
+(VFP and VDP) and ``VRT_RemoveFilter()`` to remove it. A filter pair needs
+at least one member of the pair.
+
+The ``varnishtest -i`` option no longer works outside of a Varnish source
+tree. There shouldn't be a reason to use ``-i`` outside of the Varnish
+test suite.
 
 *eof*