[master] 83b0190f0 first round of release docs

Nils Goroll nils.goroll at uplex.de
Wed Mar 11 09:02:07 UTC 2020

commit 83b0190f091c39de625ae8de921a3648505aed3d
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Wed Mar 11 09:57:34 2020 +0100

    first round of release docs
    I went through changes.rst and carried all aspects over to the release
    docs which I considered relevant.
    Please feel free to polish, I will not be able to get back to this today.

diff --git a/doc/changes.rst b/doc/changes.rst
index 478e3083c..bcd4659cb 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -92,8 +92,8 @@ Varnish Cache 6.4.0 (2019-09-16)
 * The ``if-range`` header is now handled, allowing clients to conditionally
   request a range based on a date or an ETag.
-* Introduced struct reqtop to hold information on the ESI top request
-  and PRIV_TOP, fixed regression 3019_
+* Introduced ``struct reqtop`` to hold information on the ESI top
+  request and ``PRIV_TOP``, fixed regression 3019_
 * Allow numerical expressions in VCL to be negative / negated
@@ -187,12 +187,12 @@ Varnish Cache 6.4.0 (2019-09-16)
 * Fixed a case where ``send_timeout`` would have no effect when
   streaming from a backend fetch, see bug 3189_
-* Added ``VSB_tofile()`` to ``libvarnishapi``, see 3238_
   *NOTE* Users upgrading varnish should re-check ``send_timeout`` with
   respect to long pass and streaming fetches and watch out for
   increased session close rates.
+* Added ``VSB_tofile()`` to ``libvarnishapi``, see 3238_
 .. _1853: https://github.com/varnishcache/varnish-cache/issues/1853
 .. _2418: https://github.com/varnishcache/varnish-cache/issues/2418
 .. _3009: https://github.com/varnishcache/varnish-cache/issues/3009
diff --git a/doc/sphinx/whats-new/changes-6.4.rst b/doc/sphinx/whats-new/changes-6.4.rst
index dd10e7e9c..642d52503 100644
--- a/doc/sphinx/whats-new/changes-6.4.rst
+++ b/doc/sphinx/whats-new/changes-6.4.rst
@@ -5,7 +5,7 @@ Changes in Varnish 6.4.0
 For information about updating your current Varnish deployment to the
-new version, see :ref:`whatsnew_upgrading_CURRENT`.
+new version, see :ref:`whatsnew_upgrading_6.4`.
 A more detailed and technical account of changes in Varnish, with
 links to issues that have been fixed and pull requests that have been
@@ -16,8 +16,13 @@ merged, may be found in the `change log`_.
+Numerous bugs have been fixed.
+Generic Parameter Handling
 Some parameters have dependencies and those are better documented now. For
 example :ref:`ref_param_thread_pool_min` can't be increased above
@@ -43,51 +48,133 @@ the error message::
     (attempting to set param 'thread_pool_reserve' to '100')
-**XXX changes in -p parameters**
+* Raised the minimum for the ``vcl_cooldown`` parameter to 1 second.
+Changes in behavior
+* The ``if-range`` header is now handled, allowing clients to conditionally
+  request a range based on a date or an ETag.
-Other changes in varnishd
+* Output VCC warnings also for VCLs loaded via the ``varnishd -f``
+  option
 Changes to VCL
+* backend ``none`` was added for "no backend".
+  It can be used whenever a backend is needed for syntactical
+  reasons. The ``none`` backend will fail any attempt to use it.
+* ``std.rollback(bereq)`` is now safe to use
+* Deliberately closing backend requests through ``return(abandon)``,
+  ``return(fail)`` or ``return(error)`` is no longer accounted as a
+  fetch failure
+* Numerical expressions can now be negative or negated as in ``set
+  resp.http.o = -std.integer("-200");``
+* Overloaded the ``+=`` operator to also append to headers as in ``set
+  reqp.http.header += "add this"``
 VCL variables
-**XXX new, deprecated or removed variables, or changed semantics**
-Other changes to VCL
+* Add more vcl control over timeouts with ``sess.timeout_linger``,
+  ``sess.send_timeout`` and ``sess.idle_send_timeout``
-**XXX changes in the bundled VMODs**
+* Imported ``vmod_cookie`` from `varnish_modules`_
+  The previously deprecated function ``cookie.filter_except()`` has
+  been removed during import. It was replaced by ``cookie.keep()``
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
+* A ``Notice`` VSL tag has been added
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
+* New ``pid`` command in the Varnish CLI, to get the master and optionally
+  cache process PIDs, for example from ``varnishadm``.
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
+* Add vi-stype CTRL-f / CTRL-b for page down/up to interactive
+  varnishstat
+* The ``MAIN.sess_drop`` counter is gone.
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
+* Added ``rx_close_idle`` counter for separate accounting when
+  ``timeout_idle`` is reached. Also, ``send_timeout`` is no longer
+  reported as "remote closed".
 Changes for developers and VMOD authors
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
+* New configure switch: --with-unwind. Alpine linux appears to offer a
+  ``libexecinfo`` implementation that crashes when called by Varnish, this
+  offers the alternative of using ``libunwind`` instead.
+* The option ``varnishtest -W`` is gone, the same can be achieved with
+  ``varnishtest -p debug=+witness``. A ``witness.sh`` script is available
+  in the source tree to generate a graphviz dot file and detect potential
+  lock cycles from the test logs.
+* Introduced ``struct reqtop`` to hold information on the ESI top request
+  and ``PRIV_TOP``
+* New or improved Coccinelle semantic patches that may be useful for
+  VMOD or utilities authors.
+* Added ``VSLs()`` and ``VSLbs()`` functions for logging ``STRANDS`` to
+  VSL
+* Added ``WS_VSB_new()`` / ``WS_VSB_finish()`` for VSBs on workspaces
+* added ``v_dont_optimize`` attribute macro to instruct compilers
+  (only gcc as of this release) to not optimize a function
+* Added ``VSB_tofile()`` to ``libvarnishapi``
+* It is now possible for VMOD authors to customize the connection pooling
+  of a dynamic backend. A hash is now computed to determine uniqueness and
+  a backend declaration can contribute arbitrary data to influence the pool.
+* ``VRB_Iterate()`` signature has changed
+* ``VRT_fail()`` now also works from director code
+* ``body_status`` and ``req_body_status`` have been collapsed into one
+  type. In particular, the ``REQ_BODY_*`` enums now have been replaced
+  with ``BS_*``.
+* Added ``VRT_AllocStrandsWS()`` as a utility function to allocate
+  STRANDS on a workspace.
+log tools
+* Log records can safely have empty fields or fields containing blanks
+  if they are delimited by "double quotes". This was applied to
+  ``SessError`` and ``Backend_health``.
+  Authors of log handling tools might need to review this change.
diff --git a/doc/sphinx/whats-new/upgrading-6.4.rst b/doc/sphinx/whats-new/upgrading-6.4.rst
index a65f41bef..1962681e2 100644
--- a/doc/sphinx/whats-new/upgrading-6.4.rst
+++ b/doc/sphinx/whats-new/upgrading-6.4.rst
@@ -4,26 +4,53 @@
 Upgrading to Varnish 6.4.0
-**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
+Upgrading to Varnish 6.4 from 6.3 should not require any changes
+to VCL.
-* Elements of VCL that have been removed or are deprecated, or whose
-  semantics have changed.
+This document contains information about other relevant aspects which
+should be considered when upgrading.
-* -p parameters that have been removed or are deprecated, or whose
-  semantics have changed.
-* Changes in the CLI.
+* The hash algorithm of the ``hash`` director was changed, so backend
+  selection will change once only when upgrading.
-* Changes in the output or interpretation of stats or the log, including
-  changes affecting varnishncsa/-hist/-top.
+  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.
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+* We fixed a case where ``send_timeout`` had no effect when streaming
+  from a backend fetch.
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
-  clients.
+  Users with long running backend fetches should watch out of
+  increases connection close rates and consider increasing
+  ``send_timeout`` appropriately.
+  The timeout can also be set per connection from vcl as
+  ``sess.send_timeout``.
+* 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".
+* 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 {}``.
+  Users of this timestamp should be aware that it now includes
+  ``vcl_synth {}`` processing time and appears at a different
+  position.
+* A ``Notice`` VSL tag has been added

More information about the varnish-commit mailing list