diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml index 776de7203e..0d80c7e417 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml @@ -1173,38 +1173,50 @@ 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: -

- +
+ jOOQ and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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
    • -
+

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. +

+

+ 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: -

+

+ 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 rules 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. )

- -
+ + +

jOOQ-codegen and jOOQ-meta

+

+ While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception. +

+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml index 09369d7451..1e64f4f3dd 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml @@ -1472,38 +1472,50 @@ 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: -

- +
+ jOOQ and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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
    • -
+

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. +

+

+ 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: -

+

+ 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 rules 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. )

- -
+ + +

jOOQ-codegen and jOOQ-meta

+

+ While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception. +

+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml index 1ca72a38f4..9d97907ccb 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml @@ -2839,45 +2839,50 @@ fun main(args: Array) { -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml index f6e57a8487..34e64effb9 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml @@ -2838,45 +2838,50 @@ fun main(args: Array) { -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.12.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.12.xml index aba89a889a..ec6e64ca56 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.12.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.12.xml @@ -2865,8 +2865,9 @@ fun main(args: Array) {
jOOQ and backwards-compatibility +

Semantic versioning

- 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: + jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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.
    • @@ -2876,7 +2877,7 @@ fun main(args: Array) {

    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 + Backwards-compatibility is important to jOOQ. You've chosen jOOQ as a strategic SQL engine and you don't want your SQL to break.

    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: @@ -2888,12 +2889,16 @@ fun main(args: Array) {

- 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: + 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 rules 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. ) -

+
    +
  • jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +

jOOQ-codegen and jOOQ-meta

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml index 1d2e646422..d2125026aa 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml @@ -1521,45 +1521,50 @@ 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. ) +

+ jOOQ and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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. +

+

+ 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml index fc0e8f333b..b752c6c41a 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml @@ -1981,45 +1981,50 @@ DSL.using(sql.connection) -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml index 427ecab59f..b3bc89c586 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml @@ -2479,45 +2479,50 @@ DSL.using(sql.connection) -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml index d0ea3d0aef..a95d3aa2fe 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml @@ -2679,45 +2679,50 @@ DSL.using(sql.connection) -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml index 698b33723d..6819587c37 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml @@ -2683,45 +2683,50 @@ DSL.using(sql.connection) -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml index 3002eeef45..83f100a556 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml @@ -2826,45 +2826,50 @@ fun main(args: Array) { -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml index 77cb3ce9ef..0c4777dce7 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml @@ -2840,45 +2840,50 @@ fun main(args: Array) { -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +
diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml index 6b07473ff8..12cf7edcd8 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml @@ -2839,45 +2839,50 @@ fun main(args: Array) { -
- 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 and backwards-compatibility + +

Semantic versioning

+

+ jOOQ's understanding of backwards compatibility is inspired by the rules of semantic versioning according to http://semver.org. 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 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. +

+

+ 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
    • +

- jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. ) + 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 rules 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. ).
    • +
  • Binary compatibility can be expected from patch releases, but not from minor releases as it is not practical to maintain binary compatibility in an internal DSL.
    • +
  • Source compatibility can be expected from patch and minor releases.
    • +
  • Behavioural compatibility can be expected from patch and minor releases.
    • +
  • Any jOOQ SPI XYZ that is meant to be implemented ships with a DefaultXYZ or AbstractXYZ, which can be used safely as a default implementation.
    • +
+

jOOQ-codegen and jOOQ-meta

While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.

- -
+ +