[master] 965a1f4e5 release docs polish

[Nils Goroll]

commit 965a1f4e53f1d05014cd0daacdf919cd4f306c6e
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Fri Mar 13 09:29:10 2020 +0100

    release docs polish

diff --git a/doc/sphinx/whats-new/upgrading-6.4.rst b/doc/sphinx/whats-new/upgrading-6.4.rst
index 1962681e2..53ead0a4a 100644
--- a/doc/sphinx/whats-new/upgrading-6.4.rst
+++ b/doc/sphinx/whats-new/upgrading-6.4.rst
@@ -18,16 +18,27 @@ varnishd
 
   Users of the ``hash`` director are advised to consider using the
   ``shard`` director instead, which, amongst other advantages, offers
-  more stable backend selection through consistent hashing.
+  more stable backend selection through consistent hashing. See
+  :ref:`vmod_directors(3)` for details.
 
-* We fixed a case where ``send_timeout`` had no effect when streaming
-  from a backend fetch.
+* We fixed a case where ``send_timeout`` had no effect on HTTP/1
+  connections when streaming from a backend fetch, in other words, a
+  connection might not have got closed despite the ``send_timeout``
+  having been reached. HTTP/2 was not affected.
 
-  Users with long running backend fetches should watch out of
-  increases connection close rates and consider increasing
-  ``send_timeout`` appropriately.
+  When ``send_timeout`` is reached on HTTP/1, the ``MAIN.sc_tx_error``
+  is increased and a ``Debug`` message ``Hit total send timeout, wrote
+  = x/y; not retrying`` is logged.
 
-  The timeout can also be set per connection from vcl as
+  .. actually H2 is really quite different and we have a plan to
+     harmonize timeout handling across the board
+
+  Users with long running backend fetches and HTTP/1 clients should
+  watch out for an increase of the ``MAIN.sc_tx_error`` compared to
+  before the deployment and consider increasing ``send_timeout``
+  appropriately.
+
+  The timeout can also be set per connection from VCL as
   ``sess.send_timeout``.
 
 Statistics
@@ -36,20 +47,24 @@ Statistics
 * The ``MAIN.sess_drop`` counter is gone. It should be removed from
   any statistics gathering tools, if present
 
-* Added ``rx_close_idle`` counter for separate accounting when
-  ``timeout_idle`` is reached. Also, ``send_timeout`` is no longer
-  reported as "remote closed".
+* ``timeout_idle`` being reached on HTTP/1 used to be accounted to the
+  ``MAIN.rx_timeout`` statistic. We have now added the
+  ``MAIN.rx_close_idle`` counter for this case specifically.
+
+* ``send_timeout`` being reached on HTTP/1 used to be accounted to
+  ``MAIN.sc_rem_close``. Such timeout events are now accounted towards
+  ``MAIN.sc_tx_error``.
 
 vsl/logs
 --------
 
 * The ``Process`` timestamp for ``vcl_synth {}`` was wrongly issued
-  before the VCL subroutine, now it gets emitted after VCL returns for
-  consistency with ``vcl_deliver {}``.
+  before the VCL subroutine was called, now it gets emitted after VCL
+  returns for consistency with ``vcl_deliver {}``.
 
   Users of this timestamp should be aware that it now includes
   ``vcl_synth {}`` processing time and appears at a different
-  position.
+  position in the log.
 
 * A ``Notice`` VSL tag has been added