[master] 46629b2fb whats-new: First pass on upgrade notes since 7.0.0

[Dridi Boukelmoune]

commit 46629b2fbfc37f232d1184bc0dade94904c8bef0
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Tue Mar 8 12:49:03 2022 +0100

    whats-new: First pass on upgrade notes since 7.0.0

diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..2ceed9c0c 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -30,4 +30,117 @@ to:**
 * Changes in public APIs that may require changes in VMODs or VAPI/VUT
   clients.
 
+varnishd
+========
+
+Varnish now has an infrastructure in place to rename parameters or VCL
+variables while keeping a deprecated alias for compatibility.
+
+Parameters
+~~~~~~~~~~
+
+There are plans to rename certain arguments. When this happens, aliases will
+not be listed by ``param.show [-j|-l]`` commands, but they will be displayed
+by ``param.show [-j] <param>``. Systems operating on top of ``varnishadm`` or
+the Varnish CLI can be updated to anticipate this change with the help of the
+``deprecated_dummy`` parameter added for testing purposes.
+
+The deprecated ``vsm_space`` parameter was removed. It was ignored and having
+no effect since Varnish 6.0.0 and should have disappeared with the 7.0.0
+release. The sub-argument of the ``-l`` command line option that was used as
+a shorthand for ``vsm_space`` is also no longer accepted.
+
+Command line options
+~~~~~~~~~~~~~~~~~~~~
+
+A common pattern when a CLI script is used during startup is to combine the
+``-I`` option with ``-f ''`` to prevent prevent an automatic startup of the
+cache process. In this case a start command is usually present in the CLI
+script, most likely as the last command.
+
+This enables loading VCLs and potentially VCL labels which require a specific
+order if the active VCL is supposed to switch execution to labels. VCL loaded
+through the CLI script is no longer implicitly used if there is no active VCL
+yet. If no VCL was loaded through the ``-b`` or ``-f`` options it means that
+an explicit ``vcl.use`` command is needed before the ``start`` command.
+
+In the scenario described above, that would already be the case since the
+desired active VCL would likely need to be loaded last, not eligible for an
+implicit ``vcl.use`` since dependencies were loaded first. This change should
+not affect existing ``-I`` scripts, but if it does, simply add the missing
+``vcl.use`` command.
+
+Other changes in varnishd
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ESI parser now recognizes the ``onerror="continue"`` attribute of the
+``<esi:include/>`` XML tag. Other values than "continue" are simply ignored.
+Continuing has always been Varnish's behavior for ESI sub-requests, so this
+behavior is guarded by a new ``+esi_include_onerror`` feature flag.
+
+It means that by default, the top request will continue processing ESI
+fragments even if one failed during delivery. The parsing always takes the
+attribute, and the feature flag only controls whether to honor it or not.
+
+This means that the persistence of ESI objects changed and does not tolerate
+downgrades. ESI persisted before support for this attribute assumes a lack of
+such attribute and will abort the delivery if the flag is raised.
+
+varnishtest
+===========
+
+The deprecated ``err_shell`` command was removed, use ``shell -err`` instead.
+
+Changes for developers and VMOD authors
+=======================================
+
+Backends
+~~~~~~~~
+
+Backends have reference counters now to avoid the uncertainty of a task
+holding onto a dynamic backend for a long time, for example in the waiting
+list, with the risk of the backend going away during the transaction.
+
+Assignments should be replaced as such::
+
+    -lvalue = expr;
+    +VRT_Assign_Backend(&lvalue, expr);
+
+It doesn't have to be strictly assigned this way, as long as when presented to
+a VMOD a backend is accounted for as long as it is referenced.
+
+XXX: there should be a coccinelle patch to help.
+
+On the other hand, if a backend is created dynamically but is guaranteed by
+the VMOD not to be removed before its owning VCL is discarded, it can opt out
+of reference counting with ``VRT_StaticDirector()``.
+
+Filters
+~~~~~~~
+
+Two new functions ``VRT_AddFilter()`` and ``VRT_RemoveFilter()`` manage
+filters as pairs. When used as pairs, the filters must have the same name,
+otherwise operating with only one fetch or delivery filter is fine.
+
+Unlike its deprecated predecessors ``VRT_AddVFP()`` and ``VRT_AddVDP()``,
+the new ``VRT_AddFilter()`` returns an error string. The ``VRT_RemoveVFP()``
+and ``VRT_RemoveVDP()`` functions are also deprecated an simply thin wrapper
+lacking error handling around the new functions.
+
+VMOD deprecated aliases
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A VMOD author can from now on rename a function or object method without
+immediately breaking compatibility by declaring the old name as an alias.
+
+In the VMOD descriptor, it is possible to add the following stanza::
+
+    $Alias deprecated_function original_function
+
+    or
+
+    $Alias .deprecated_method objec.original_method
+
+This is a good occasion to revisit unfortunate name choices in existing VMODs.
+
 *eof*