From 0f9da660235007268a7f0f33d97abd6d568ea6cb Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Thu, 20 Dec 2012 14:23:59 +0100 Subject: [PATCH] [#2027] Document semantic versioning rules as understood by jOOQ --- .../src/main/resources/manual-3.0.xml | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/jOOQ-website/src/main/resources/manual-3.0.xml b/jOOQ-website/src/main/resources/manual-3.0.xml index 1a04d93936..a2b45c2f13 100644 --- a/jOOQ-website/src/main/resources/manual-3.0.xml +++ b/jOOQ-website/src/main/resources/manual-3.0.xml @@ -971,6 +971,39 @@ object Test { //

+ +
+ jOOQ and backwards-compatibility + +

+ jOOQ follows the rules of semantic versioning according to http://semver.org quite strictly. Those rules impose a versioning scheme [X].[Y].[Z] that can be summarised as follows: +

+
    +
  • If a patch release includes bugfixes, performance improvements and API-irrelevant new features, [Z] is incremented by one.
    • +
  • If a minor release includes backwards-compatible, API-relevant new features, [Y] is incremented by one and [Z] is reset to zero.
    • +
  • If a major release includes backwards-incompatible, API-relevant new features, [X] is incremented by one and [Y], [Z] are reset to zero.
    • +
+ +

jOOQ's understanding of backwards-compatibility

+

+ Backwards-compatibility is important to jOOQ. You've chosen jOOQ as a strategic SQL engine and you don't want your SQL to break. That is why there is at most one major release per year, which changes only those parts of jOOQ's API and functionality, which were agreed upon on the user group. During the year, only minor releases are shipped, adding new features in a backwards-compatible way +

+

+ However, there are some elements of API evolution that would be considered backwards-incompatible in other APIs, but not in jOOQ. As discussed later on in the section about , much of jOOQ's API is indeed an internal domain-specific language implemented mostly using Java interfaces. Adding language elements to these interfaces means any of these actions: +

+
    +
  • Adding methods to the interface
    • +
  • Overloading methods for convenience
    • +
  • Changing the type hierarchy of interfaces
    • +
+ +

+ It becomes obvious that it would be impossible to add new language elements (e.g. new , new ) to the API without breaking any client code that actually implements those interfaces. Hence, the following rule should be observed: +

+ +

jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. )

+ +