[master] 66717e51d Release docs: Rewrite ESI onerror="continue"

[Nils Goroll]

commit 66717e51dde040d1085d20331ff4e1aed7920c08
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Mon Mar 14 14:25:31 2022 +0100

    Release docs: Rewrite ESI onerror="continue"
    
    I found the previous wording confusing and hope this is considered an improvement.
    
    We should make clear that lack of onerror="continue" implies abort only if
    the feature flag is set.

diff --git a/doc/changes.rst b/doc/changes.rst
index a09738826..162a1f847 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -50,8 +50,15 @@ Varnish Cache NEXT (2022-03-15)
   promoted to a regular feature or dropped without being considered a
   breaking change.
 
-* ESI includes now support the ``onerror="continue"``
-  attribute if the ``+esi_include_onerror`` feature flag is set.
+* ESI includes now support the ``onerror="continue"`` attribute of
+  ``<esi:include/>`` tags.
+
+  The ``+esi_include_onerror`` feature flag controls if the attribute
+  is honored: If enabled, failure of an include stops ESI processing
+  unless the ``onerror="continue"`` attribute was set for it.
+
+  The feature flag is off by default, preserving the existing behavior
+  to continue ESI processing despite include failures.
 
 * The deprecated sub-argument of the ``-l`` option was removed, it is
   now a shorthand for the ``vsl_space`` parameter only.
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index d516efc75..fa1b77d56 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -75,18 +75,24 @@ not affect existing ``-I`` scripts, but if it does, simply add the missing
 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.
+The ESI parser now recognizes the ``onerror="continue"`` attribute of
+the ``<esi:include/>`` XML tag.
+
+The ``+esi_include_onerror`` feature flag controls if the attribute is
+honored: If enabled, failure of an include stops ESI processing unless
+the ``onerror="continue"`` attribute was set for it.
+
+The feature flag is off by default, preserving the existing behavior
+to continue ESI processing despite include failures.
+
+Users of persistent storage engines be advised that objects created
+before the introduction of this change can not carry the
+``onerror="continue"`` attribute and, consequently, will be handled as
+if it was not present if the ``+esi_include_onerror`` feature flag is
+enabled.
+
+Also, as this change is not backwards compatible, downgrades with
+persisted storage are not supported across this release.
 
 varnishtest
 ===========