diff options
author | Jan Christopher Vogt <oss.nsp@cvogt.org> | 2017-03-11 18:58:56 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-03-11 18:58:56 -0500 |
commit | 4eb753e4d4ef5be7443b99832892bac697b10b50 (patch) | |
tree | d9200d33f7d2f9b1ed9884330fcd4c6ca651f44a /doc/cbt-developer/version-compatibility.md | |
parent | e760ee9e4c4c3b3f39e2bb2dfd47d2b142e12a53 (diff) | |
parent | cf859909fbcf577bac92d9f35f5d11e638a66177 (diff) | |
download | cbt-4eb753e4d4ef5be7443b99832892bac697b10b50.tar.gz cbt-4eb753e4d4ef5be7443b99832892bac697b10b50.tar.bz2 cbt-4eb753e4d4ef5be7443b99832892bac697b10b50.zip |
Merge pull request #412 from cvogt/chris
various
Diffstat (limited to 'doc/cbt-developer/version-compatibility.md')
-rw-r--r-- | doc/cbt-developer/version-compatibility.md | 50 |
1 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. |