[master] f7869e8e9 doc: upgrading

[Nils Goroll]

commit f7869e8e98167ceae3189d027f42ccb421cb5e72
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Mon Sep 14 10:40:20 2020 +0200

    doc: upgrading

diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 57dcb87b3..04bf7938d 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -171,6 +171,8 @@ VMOD authors who would like to generate VCC files can now use the
 ``VARNISH_VMODS_GENERATED()`` macro from ``varnish.m4`` for autotools
 builds.
 
+.. _whatsnew_changes_CURRENT_workspace:
+
 Workspace API
 ~~~~~~~~~~~~~
 
@@ -202,6 +204,8 @@ Other VRT / cache.h changes
 
 * Added ``VRT_BLOB_string()`` for the default BLOB folding documented above
 
+.. _whatsnew_changes_CURRENT_vsc:
+
 libvarnishapi
 ~~~~~~~~~~~~~
 
@@ -219,6 +223,8 @@ they are all tested in order and the first to match determines the outcome.
 The ``'R'`` argument takes precedence over regular filtering and can be used
 to ensure that some counters are present regardless of user configuration.
 
+.. _whatsnew_changes_CURRENT_libvarnish:
+
 libvarnish
 ~~~~~~~~~~
 
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 27cb67c94..b92602c12 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -61,8 +61,10 @@ After::
     }
   }
 
-TODO: a word on ``varnishstat -f`` being deprecated and ``-{I,X}`` being
-order-sensitive.
+The filter option ``-f`` is now deprecated in favor of the ``-I`` and
+``-X`` options for field inclusions and exclusions,
+respectively. Tools using ``varnishstat`` should prepare for future
+removal and be changed accordingly.
 
 VSL
 ===
@@ -76,9 +78,18 @@ The new query would be::
 
     varnishlog -q 'BackendClose[2] ~ www and BackendClose[3] eq recycle'
 
-libvarnishapi
-=============
+Changes relevant for VMODs and/or VAPI/VUT clients
+==================================================
 
-TODO: a similar note as ``varnishstat -f`` for ``VSC_Arg('f')``.
+* VMODs using the Workspace API might need minor adjustments, see
+  :ref:`whatsnew_changes_CURRENT_workspace`.
+
+* ``VSC_Arg('f')`` is now deprecated and should be rewritten to use
+  ``VSC_Arg('I')`` / ``VSC_Arg('X')``, see above note on
+  `varnishstat`_ and :ref:`whatsnew_changes_CURRENT_vsc`.
+
+* VSB support for dynamic vs. static allocations has been changed and
+  code using VSBs will need to be adjusted, see
+  :ref:`whatsnew_changes_CURRENT_libvarnish`.
 
 *eof*