From: Petr Špaček <petr.spacek@nic.cz>
Date: Wed, 7 Oct 2020 14:02:51 +0000 (+0200)
Subject: doc: document what version number means
X-Git-Tag: v5.2.0~21^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=eb1793e47dd9cb68f96b88d427e6e1c0740cb6dd;p=thirdparty%2Fknot-resolver.git

doc: document what version number means

Result of discussion in MR
https://gitlab.nic.cz/knot/knot-resolver/-/merge_requests/1075
---

diff --git a/doc/NEWS.rst b/doc/NEWS.rst
index 0c44b7c16..596484a39 100644
--- a/doc/NEWS.rst
+++ b/doc/NEWS.rst
@@ -6,5 +6,31 @@
 Release notes
 *************
 
+Version numbering
+=================
+Version number format is ``major.minor.patch``.
+Knot Resolver does not use semantic versioning even though the version number looks similar.
+
+Leftmost number which was changed signalizes what to expect when upgrading:
+
+Major version
+    * Manual upgrade steps might be necessary, please follow instructions in :ref:`Upgrading` section.
+    * Major releases may contain significant changes including changes to configuration format.
+    * We might release a new major also when internal implementation details change significantly.
+
+Minor version
+   * Configuration stays compatible with the previous version, except for undocumented or very obscure options.
+   * Upgrade should be seamless for users who use modules shipped as part of Knot Resolver distribution.
+   * Incompatible changes in internal APIs are allowed in minor versions. Users who develop or use custom modules
+     (i.e. modules not distributed together with Knot Resolver) need to double check their modules for incompatibilities.
+     :ref:`Upgrading` section should contain hints for module authors.
+
+Patch version
+    * Everything should be compatible with the previous version.
+    * API for modules should be stable on best effort basis, i.e. API is very unlikely to break in patch releases.
+    * Custom modules might need to be recompiled, i.e. ABI compatibility is not guaranteed.
+
+This definition is not applicable to versions older than 5.2.0.
+
 .. include:: ../NEWS
 
diff --git a/doc/upgrading.rst b/doc/upgrading.rst
index c7222166d..efe9d0019 100644
--- a/doc/upgrading.rst
+++ b/doc/upgrading.rst
@@ -10,6 +10,7 @@ This section summarizes steps required when upgrading to newer Knot Resolver ver
 We advise users to also read :ref:`release_notes` for respective versions.
 Section *Module changes* is relevant only for users who develop or use third-party modules.
 
+
 Upcoming changes
 ================