meson: doc/migration - document significant changes

diff --git a/NEWS b/NEWS
index 1f8147f9f1a66327ab2d1ddb09866029961d9a8c..8e0da5813a466ba11aba83e43b80d63af1a84361 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,9 +1,15 @@
-Knot Resolver 3.x.y (2019-0m-dd)
+Knot Resolver 4.0.0 (2019-0m-dd)
 ================================
 
 Incompatible changes
 --------------------
-- libknot >= 2.7.6 is required
+- see migration guide:
+  https://knot-resolver.readthedocs.io/en/v4.0.0/migration.html#upgrade-from-3-to-4
+- meson build system is now used for builds (!771)
+- build with embedded LMBD is no longer supported
+- default modules dir location has changed
+- DNSSEC is enabled by default
+- upstream packages for Debian now require systemd
 
 Improvements
 ------------
@@ -11,6 +17,7 @@ Improvements
 - hints module: allow configuring the TTL and change default from 0 to 5s
 - policy module: policy.rpz() will watch the file for changes by default
 - packaging: lua cqueues added to default dependencies where available
+- systemd: service is no longer auto-restarted on configuration errors
 
 Bugfixes
 --------

diff --git a/doc/build.rst b/doc/build.rst
index 03d8847f0bb797e2a35157cc68964b7d7bbc91db..3f4702d183f35b52dbc51b4880d3a3ec562f4065 100644 (file)
--- a/doc/build.rst
+++ b/doc/build.rst
@@ -1,3 +1,5 @@
+.. _build:
+
 Building from sources
 =====================
 
@@ -233,6 +235,8 @@ It's also possible to make a development snapshot tarball:
 
    $ ./scripts/make-dev-archive.sh
 
+.. _packaging:
+
 Packaging
 ---------
 

diff --git a/doc/index.rst b/doc/index.rst
index 683c77cf37fe712eb05dc4e3f5b88502a47ed12e..9726495ad283ffed81eb8ca69b65719545ff9720 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,6 +14,7 @@ and it provides a state-machine like API for extensions.
    build
    lib
    modules_api
+   migration
    NEWS
 
 

diff --git a/doc/migration.rst b/doc/migration.rst
new file mode 100644 (file)
index 0000000..d2de479
--- /dev/null
+++ b/doc/migration.rst
@@ -0,0 +1,68 @@
+*********
+Migration
+*********
+
+.. _upgrade-from-3-to-4:
+
+Upgrade from 3.x to 4.x
+=======================
+
+Users
+-----
+
+* DNSSEC validation is now turned on by default. If you need to disable it, see
+  :ref:`dnssec-config`.
+* In case you are using your own custom modules, move them to the new module
+  location. The exact location depends on your distribution. Generally, modules previously
+  in ``/usr/lib/kdns_modules`` should be moved to ``/usr/lib/knot-resolver/kres_modules``.
+
+Packagers & Developers
+----------------------
+
+* Knot DNS >= 2.8 is required.
+* meson >= 0.46 and ninja is required.
+* meson build system is now used for compiling the project. For instructions, see
+  the :ref:`build`. Packagers should pay attention to section :ref:`packaging`
+  for information about systemd unit files and trust anchors.
+* Embedding LMDB is no longer supported, lmdb is now required as an external dependency.
+* Trust anchors file from upstream is installed and used as default unless you
+  override ``keyfile_default`` during build.
+
+Module changes
+~~~~~~~~~~~~~~
+
+* Default module location has changed from ``{libdir}/kdns_modules`` to
+  ``{libdir}/knot-resolver/kres_modules``. Modules are now in the lua namespace
+  ``kres_modules.*``.
+* ``kr_straddr_split()`` API has changed.
+
+
+Upgrade from 2.x to 3.x
+=======================
+
+Users
+-----
+
+* ``hints.use_nodata(true)`` by default.
+* In case you wrote custom Lua modules, please consult :ref:`significant-lua-changes`.
+* Removed modules: ``cookie`` (temporarily) and ``version`` (permanently).
+
+Packagers & Developers
+----------------------
+
+* Knot DNS >= 2.7.2 is required.
+* cache: fail lua operations if cache isn't open yet (!639)
+  By default cache is opened *after* reading the configuration,
+  and older versions were silently ignoring cache operations.
+  Valid configuration must open cache using `cache.open()` or `cache.size =`
+  before executing cache operations like `cache.clear()`.
+
+Modules changes
+~~~~~~~~~~~~~~~
+
+* New layer was added: ``answer_finalize``.
+* ``kr_request`` keeps ``::qsource.packet`` beyond the ``begin`` layer.
+* ``kr_request::qsource.tcp`` renamed to ``::qsource.flags.tcp``.
+* ``kr_request::has_tls`` renamed to ``::qsource.flags.tls``.
+* ``kr_zonecut_add()``, ``kr_zonecut_del()`` and ``kr_nsrep_sort()`` changed
+  parameters slightly.

diff --git a/lib/README.rst b/lib/README.rst
index 290567600f4b3b4a71fbe99adcaa71e7ea51b304..077330fb1d6a7ec8b1b82e6d08bee7fe1c47b095 100644 (file)
--- a/lib/README.rst
+++ b/lib/README.rst
@@ -108,7 +108,7 @@ This is only passive processing of the incoming answer. If you want to change th
        {
                struct kr_request *req = ctx->req;
                struct kr_query *qry = req->current_query;
-               
+
                /* Query can be satisfied locally. */
                if (can_satisfy(qry)) {
                        /* This flag makes the resolver move the query
@@ -278,6 +278,8 @@ As described in the layers, you can not only retrieve information about current
 .. _bindings: https://gitlab.labs.nic.cz/knot/knot-resolver/blob/master/daemon/lua/kres.lua
 
 
+.. _significant-lua-changes:
+
 Significant Lua API changes
 ---------------------------