[5.2] 1156b8e Some work on the release docs

[PÃ¥l Hermunn Johansen]

commit 1156b8ea6b4cf7c142e40a6a61050223f90215fd
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Wed Sep 13 08:46:46 2017 +0000

    Some work on the release docs

diff --git a/doc/sphinx/whats-new/changes-5.2.rst b/doc/sphinx/whats-new/changes-5.2.rst
index 4804a86..5688246 100644
--- a/doc/sphinx/whats-new/changes-5.2.rst
+++ b/doc/sphinx/whats-new/changes-5.2.rst
@@ -3,26 +3,15 @@
 Changes in Varnish 5.2
 ======================
 
-*XXX: preamble*
-
-Varnish statistics
-~~~~~~~~~~~~~~~~~~
-
-The export of statistics counters via shared memory has been
-overhauled to get rid of limitations which made sense 11 years
-ago but not so much now.
-
-Statistics counters are now self-describing in shared memory,
-paving the way so that VMODs or maybe even VCL can define
-counters in the future, and have them show up in varnishstat
-and other VSC-API based programs.
+Varnish 5.2 is mostly changes under the hood so most varnish
+installations will be able to upgrade with no modifications.
 
 .. _whatsnew_new_vmods:
 
 New VMODs in the standard distribution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*XXX: introductory paragraphs about new VMODs*
+We have added three new VMODs to the varnish project.
 
 VMOD blob
 ---------
@@ -30,7 +19,7 @@ VMOD blob
 We have added the variables ``req.hash`` and ``bereq.hash`` to VCL,
 which contain the hash value computed by Varnish for the current
 request, for use in cache lookup. Their data type is BLOB, which
-represents arbitrary data of any length -- the new variables contain
+represents opaque data of any length -- the new variables contain
 the raw binary hashes.
 
 This is the first time that an element of standard VCL has the BLOB
@@ -39,17 +28,34 @@ have added VMOD blob to facilitate their use. In particular, the VMOD
 implements binary-to-text encodings, for example so that you can
 assign the hash to a header as a base64 or hex string. It also
 provides some other utilities such as getting the length of a BLOB or
-testing BLOBs for equality. See :ref:`vmod_blob(3)`.
+testing BLOBs for equality.
+
+See :ref:`vmod_blob(3)`.
 
 VMOD purge
 ----------
 
-*XXX: about VMOD purge*
+*XXX: DRIDI ?  about VMOD purge*
+
+See :ref:`vmod_purge(3)`.
 
 VMOD vtc
 --------
 
-*XXX: about VMOD vtc*
+As long as we have had VMODs, we had an internal vmod called ``vmod_debug`` 
+which were used with ``varnishtest`` to exercise the VMOD related parts of
+``varnishd``.  Over time this vmod grew other useful functions for writing
+test-cases.
+
+We only distribute ``vmod_debug`` in source releases, because it has some
+pretty evil functionality, for instance ``debug.panic()``.
+
+We have split the non-suicidal test-writing stuff from ``vmod_debug``
+into a new ``vmod_vtc``, which is included in binary releases from
+now on, in order to make it easier for people to use ``varnishtest``
+to test local configurations, VMODs etc.
+
+See :ref:`vmod_vtc(3)`.
 
 XXX: Any other headline changes ...
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,11 +67,34 @@ News for authors of VMODs and Varnish API client applications
 
 *XXX: such news may include:*
 
+
+$ABI [strict|vrt]
+-----------------
+
+*XXX: DRIDI ?*
+
 VSM/VSC API changes
 -------------------
 
-The rewrite of the VSM/VSC code has similified the API and
-made it much more robust, and code calling into these APIs
+The export of statistics counters via shared memory has been
+overhauled to get rid of limitations which made sense 11 years
+ago but not so much now.
+
+A set of statistics counters are now fully defined in a ``.vsc``
+file which is processed by the ``vsctool.py`` script into a .c and
+.h file, which is compiled into the relevant body of code.
+
+This means that statistics counters are now self-describing in
+shared memory, and ``varnishstat`` or other VSC-API using programs
+have no compiled in knowledge about which counters exist or how
+to treat them.
+
+This paves the way for VMODs or maybe even VCL to define
+custom counters, and have them show up in varnishstat and
+other VSC-API based programs just like the rest of the counters.
+
+The rewrite of the VSM/VSC code similified both APIs and
+made them much more robust but code calling into these APIs
 will have to be updated to match.
 
 The necessary changes mostly center around detecting if the
@@ -74,10 +103,10 @@ varnishd management/worker process has restarted.
 In the new VSM-api once setup is done, VSM_Attach() latches
 on to a running varnishd master process and stays there.
 
-VSM_Status() returns information about the master and worker
-process, if they are running, if they have been restarted
-(since the previous call to VSM_Status()) and updates the
-in-memory list of VSM segments.
+VSM_Status() updates the in-memory list of VSM segments, and
+returns information about the master and worker proces:
+Are they running?  Have they been restarted?  Have VSM segments
+been added/deleted?
 
 Each VSM segment is now a separate piece of shared memory
 and the name of the segment can be much longer now.
@@ -89,6 +118,6 @@ should be called to release the segment again.
 
 All in all, this should be simpler and more robust now.
 
-* *XXX: changes in VRT*
+*XXX: changes in VRT*
 
 *EOF*
diff --git a/doc/sphinx/whats-new/upgrading-5.2.rst b/doc/sphinx/whats-new/upgrading-5.2.rst
index cc70923..2164e32 100644
--- a/doc/sphinx/whats-new/upgrading-5.2.rst
+++ b/doc/sphinx/whats-new/upgrading-5.2.rst
@@ -7,8 +7,8 @@ Upgrading to Varnish 5.2
 Varnish statistics and logging
 ==============================
 
-*XXX: anything new for users or admins concerning statistics,*
-*varnishstat, logging etc*
+There are extensive changes under the hood with respect to statistics
+counters, but these should all be transparent at the user-level.
 
 varnishd parameters
 ===================