Document the new leapp-framework capability

See the commit d37e2b4 for more info about the capability.

docs/source/compatibility-with-leapp-repository.md

@@ -0,0 +1,59 @@
+# Compatibility between leapp and leapp repositories
+
+There is a hidden dragon in the split of leapp framework and leapp repositories
+projects. The development of features and incompatible changes have different
+speed in both projects. As we want to release our projects using semantic
+versioning and in the same time, we do not want to release a new version of
+the project after each merge of a new feature or incompatible change.
+We rather prefer releasing new versions with changelogs and everything
+when we agree it's worthwhile.
+
+But during the time we have changes just in the upstream (master) branches,
+we need to ensure we are able to sync other leapp-repositories projects with
+the current devel changes. For these pruposes the `leapp-framework` capability
+is provided in framework (python[23]-leapp) rpms.
+
+## When and how change the capability
+
+The `leapp-framework` capability has to be changed in case of any change of
+provided API (e.g. change in the leapp standard library) or functionality that
+could affect actors in leapp repositories. That includes new features as well
+as an actor may depend on that in future, and the leapp-repository package
+should be able to specify correct framework version that is needed.
+
+The `leapp-framework` capability uses just `X.Y` versioning:
+
+- In case of a change breaking previous functionality (e.g. changed a name of a function) provided by framework, bump `X` and set `Y` to 0.
+- In case of a new feature (e.g. added new function in stdlib), that doesn't affect already existing actors, bump `Y`
+
+The value of the capability should be bumped per PR providing all changes.
+IOW, when a PR implements two compatible/incompatible changes in several
+commits, the value should be bumped only once!
+
+As well it is recommended to mentioned the value of the capability
+(when changed) in the commit msg, so it the tracking is easy.
+
+## Suggested dependency in leapp-repository rpms
+We suggest to set dependency on the `leapp-framework` capability in any rpm
+with containing leapp repositories in this way:
+
+```spec
+Requires:       leapp-framework >= 1.2, leapp-framework < 2
+```
+
+Which means, that you want to install framework of version at least 1.2 but
+lower than 2 (e.g. 1.99).
+
+### Possible issue
+There is unfortunately one issue with the above solution. As far as there is just
+one rpm providing that capability, it's ok. Problem occurs on systems where
+there will be more rpms (of different name) providing the capability.
+So in case you are able to install e.g. python2-leapp and python3-leapp rpms
+on the system, you could end up with:
+
+- python2-leapp providing leapp-framework 1.0, and
+- python3-leapp providing leapp-framework 3.0
+
+which both are broken for leapp repository and the dependency from the point of
+rpms is satisfied. This should be rare case. We suggest to ensure that you
+use such repositories where only one of those rpms exists.

docs/source/infrastructure.rst

@@ -8,3 +8,4 @@ Here you can find documentation related to our CI/CD, packaging, etc.
 
     dependencies
     dependencies-leapp-repository
+    compatibility-with-leapp-repository