Start filling in the "Upgrading" socument for the March 2019 release.

doc/sphinx/whats-new/changes-trunk.rst

@@ -107,6 +107,8 @@ microsecond precision.  This affects the tags ``ExpKill`` and
 varnishadm(1) and varnish-cli(7)
 ================================
 
+.. _whatsnew_changes_cli_json:
+
 JSON output
 ~~~~~~~~~~~
 
@@ -132,6 +134,8 @@ recommend the use of JSON format.
 Added the command ``param.reset`` to reset a parameter's value to its
 default, see :ref:`varnish-cli(7)`.
 
+.. _whatsnew_changes_vcl_list_backend_list:
+
 Listing backends and VCLs
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/sphinx/whats-new/upgrading-trunk.rst

@@ -30,4 +30,45 @@ to:**
 * Changes in public APIs that may require changes in VMODs or VAPI/VUT
   clients.
 
+VCL
+===
+
+VCL programs for Varnish 6.1 can be expected to run without changes in
+the new version.
+
+A VCL load will now issue a warning, but does not fail as previously,
+if a backend declaration uses the ``.path`` field to specify a Unix
+domain socket, but the socket file does not exist or is not accessible
+at VCL load time. This makes it possible to start the peer component
+listening at the socket, or set its permissions, after Varnish starts
+or the VCL is loaded. Backend fetches fail if the socket is not
+accessible by the time the fetch is attempted.
+
+Runtime parameters
+==================
+
+Some varnishd ``-p`` parameters that have been deprecated for some
+time have been removed. If you haven't changed them yet, you have to
+now.  These are:
+
+* ``shm_reclen`` -- use :ref:`ref_param_vsl_reclen` instead
+
+* ``vcl_dir`` -- use :ref:`ref_param_vcl_path` instead
+
+* ``vmod_dir`` -- use :ref:`ref_param_vmod_path` instead
+
+varnishadm and the CLI
+======================
+
+The output formats of the ``vcl.list`` and ``backend.list`` commands
+have changed, see :ref:`whatsnew_changes_vcl_list_backend_list` and
+:ref:`varnish-cli(7)` for details. In non-JSON mode, the width of
+columns in ``backend.list`` and ``vcl.list`` output is now dynamic, to
+fit the width of the terminal window.
+
+The ``-j`` option for JSON output has been added to a number of
+commands, see :ref:`whatsnew_changes_cli_json` and
+:ref:`varnish-cli(7)`. We recommend the use of JSON format for
+automated parsing of CLI responses (:ref:`varnishadm(1)` output).
+
 *eof*