add developer documentation about cbt version compatibility

2 files changed, 50 insertions, 0 deletions

diff --git a/doc/cbt-developer/version-compatibility.md b/doc/cbt-developer/version-compatibility.md
new file mode 100644
index 0000000..986bb37
--- /dev/null
+++ b/doc/cbt-developer/version-compatibility.md
@@ -0,0 +1,50 @@
+## Why does CBT version compatiblity matter?
+CBT allows fixing the version used using the `// cbt: ` annotation.
+This means that the CBT version you installed will download the
+CBT version referenced there and use that instead. CBT also
+allows composing builds, which require different CBT versions.
+In order for all of this to work, different CBT versions need to
+be able to talk to one another.
+
+This chapter is about how the current solution works and about
+the pitfalls involved which can make a new version of CBT
+incompatible with older versions.
+
+## How can compatibility be broken?
+The current solution mostly relies on the Java interfaces in
+the `compability/` folder. Changing the Java interface in a
+non-backwards-compatible way means making the CBT incompatible with
+older versions. Java 8 default methods make this a whole lot easier
+and this is the main reason CBT relies on Java 8. But we also
+want to keep this interfaces as small as possible in order to
+minimize the risk.
+
+However there are more things that can break compatibility when changed:
+- the format of the `// cbt: ` version string
+- the name and format of Build classes (or files) that CBT looks for
+- communication between versions via reflection in particular
+  - how the TrapSecurityManager of each CBT version talks to the
+    installed TrapSecurityManager via reflection
+
+## How to detect accidental breakages?
+
+CBT's tests have a few tests with `// cbt: ` annotations and some
+reference libraries as Git dependencies that use these annotations.
+Many incompatibilities will lead to these tests failing, either with
+a compilation error against the `compatiblity/` interfaces or with
+a runtime exception or unexpected behavior in case other things are
+broken.
+
+## How an we improve the situation in the long run?
+
+In the long run we should think about how to reduce the risk
+or sometimes even unavoidability of incompatibilities.
+The unavoidability mostly stems from limitations of what Java
+interfaces can express. However Java 8 interfaces mostly work
+fairly well. We should consider using them for the cases that
+currently use reflection instead of reflection.
+
+If Java 8 interfaces still turn out to be a problem in the long run,
+we could consider an interface that we control completely, e.g.
+an internal serialization formation, which CBT versions use to talk
+to each other.
diff --git a/doc/design.txt b/doc/design.md
index 28bbdaa..28bbdaa 100644
--- a/doc/design.txt
+++ b/doc/design.md