From: Tomas Krizek <tomas.krizek@nic.cz>
Date: Thu, 28 Feb 2019 15:38:04 +0000 (+0100)
Subject: meson: doc/migration - document significant changes
X-Git-Tag: v4.0.0~24^2~42
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=edf08b197821fd6713332ecb9a5175eb9ca0afea;p=thirdparty%2Fknot-resolver.git

meson: doc/migration - document significant changes
---

diff --git a/NEWS b/NEWS
index 1f8147f9f..8e0da5813 100644
--- 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 03d8847f0..3f4702d18 100644
--- 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 683c77cf3..9726495ad 100644
--- 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
index 000000000..d2de47920
--- /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 290567600..077330fb1 100644
--- 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
 ---------------------------