Processes/coding-guidelines.md

@@ -684,6 +684,12 @@ Sometimes we need to introduce changes that are not backward compatible. If poss
 For example:
 The old `reservation-mode` parameter has been replaced with `reservations-global`, `reservations-in-subnet` and `reservations-out-of-pool` in 1.9.2. A warning should be printed if `reservation-mode` is used. Such a warning should be coded as soon as realistically possible to give people as much advance warning as possible. As such, this will be implemented in 1.9.2, so early adopters will see it right way. It will be included in 2.0, where users preferring stable will see it. The old way can be removed somewhere in 2.1.x, so 2.2 will not accept it anymore. This way people who use only stable version will have time to migrate. They'll see the warning when moving from 1.8 to 2.0 and will have time until 2.2.
 
+# DB schema versions
+
+For a long time Kea had a concept of having major and minor versions of the schema, with minor being bumped for backward compatible changes. The original idea was that it would be possible to move back and forth between releases. This was never implemented and never works, as all the backends made explicit check that both major and minor must much. Also, it is often questionable what is and what is not a backward incompatible change. Finally, we never had any chance to test this backward compatibility. As such, around June 2021, we decided to move to a simpler scheme. 
+
+When a schema is changed, we always bump major version and minor always remains at zero. Technically, we could get rid of the minor version, but we want to keep it for backward compatibility *cough*. See rationale [here](https://gitlab.isc.org/isc-projects/kea/-/merge_requests/1257#note_220860).
+
 # Guidelines Adopted by Other Projects
 
 Other projects have their own coding guidelines.  Here're some