[master] 7a3e0b3bb whats-new: Upgrade notes for VRE

[Dridi Boukelmoune]

commit 7a3e0b3bb066160060d65c789d0631565ea5e631
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Fri Sep 3 17:58:29 2021 +0200

    whats-new: Upgrade notes for VRE

diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6b1a01990..23d9d85f3 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -254,6 +254,40 @@ TODO
 VRE
 '''
 
-TODO
+The VRE API completely changed in preparation for the PCRE2 migration, in
+order to funnel all PCRE usage in the Varnish source code through VRE.
+
+Similarly to how parameters were renamed, the ``match_recursion`` field from
+``struct vre_limits`` was renamed to ``depth``. It has otherwise the same
+meaning and purpose.
+
+Notable breaking changes:
+
+- ``VRE_compile()`` signature changed
+- ``VRE_exec()`` was replaced:
+  - ``VRE_match()`` does simple matching
+  - ``VRE_capture()`` captures matched groups in a ``txt`` array
+  - ``VRE_sub()`` substitute matches with a replacement in a VSB
+- ``VRE_error()`` prints an error message for all the functions above in a VSB
+- ``VRE_export()`` packs a usable ``vre_t`` that can be persisted as a byte
+  stream
+
+The ``VRE_ERROR_NOMATCH`` symbol is now hard-linked like ``VRE_CASELESS``, and
+``VRE_NOTEMPTY`` is no longer supported. There are no match options left in
+the VRE facade but the ``VRE_match()``, ``VRE_capture()`` and ``VRE_sub()``
+functions still take an ``options`` argument to keep the ability of allowing
+match options in the future.
+
+The ``VRE_ERROR_LEN`` gives a size that should be safe to avoid truncated
+error messages in a static buffer.
+
+To gain full access to PCRE2 features from a regular expression provided via
+``vre_t`` a backend-specific ``vre_pcre2.h`` contains a ``VRE_unpack()``
+function. This opens for example the door to ``pcre2_substitute()`` with the
+PCRE2 substitution syntax and named capture groups as an alternative to VCL's
+``regsub()`` syntax backed by ``VRE_sub()``.
+
+Ideally, ``vre_pcre2.h`` will be the only breaking change next time we move
+to a different regular expression engine. Hopefully not too soon.
 
 *eof*
diff --git a/include/vre.h b/include/vre.h
index bb8702b22..854e96058 100644
--- a/include/vre.h
+++ b/include/vre.h
@@ -52,7 +52,7 @@ typedef struct vre vre_t;
 /* This maps to PCRE2 error codes */
 extern const int VRE_ERROR_NOMATCH;
 
-/* And those to PCRE2 options */
+/* And those to PCRE2 compilation options */
 extern const unsigned VRE_CASELESS;
 
 vre_t *VRE_compile(const char *, unsigned, int *, int *, unsigned);