]> git.ipfire.org Git - thirdparty/knot-resolver.git/commitdiff
doc: document what version number means
authorPetr Špaček <petr.spacek@nic.cz>
Wed, 7 Oct 2020 14:02:51 +0000 (16:02 +0200)
committerPetr Špaček <petr.spacek@nic.cz>
Thu, 8 Oct 2020 10:29:05 +0000 (12:29 +0200)
Result of discussion in MR
https://gitlab.nic.cz/knot/knot-resolver/-/merge_requests/1075

doc/NEWS.rst
doc/upgrading.rst

index 0c44b7c16ee03895d7feb4e8eaa6aa077cb86ac4..596484a396c45d362ba150cc42f2b72ed628fffb 100644 (file)
@@ -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
 
index c7222166dcfc0e126a85123d270360a89b1e87f4..efe9d00193b124a58e26b307db2ef4f87a9f25b8 100644 (file)
@@ -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
 ================