Page Comparison

...

The public API of the Java software products and libraries consists of all the public interaction points by which a developer or deployer might interact with the software (as opposed to a more constrained use of the term that refers only to Java classes and methods). This includes:

• Public and protected Java classes and methods exported from API Packages and Modules (this is defined subsequently)

• Public and protected Java classes and methods in any 3rd-party library shipped with a product and available on the classpath

• Java or Spring properties defined in product or library reference documentation

• Spring beans defined by name in product or library reference documentation

• Any configuration files and content not covered above and designated as user-modifiable by product documentation

• Documented parameters of command line scripts, utilities, installation tools, etc.

• The default address/location of remotely accessible functionality

• Data storage and logging formats that are documented

This is a non-exhaustive list intended to capture the spirit of "all the public interaction points" and is deliberately meant broadly, not narrowly. This is a constraining definition on our ability to change behavior easily as a trade-off to guaranteeing a high degree of stability and predictability.

...

The version policy addresses compatibility at the Java layer in several dimensions:

• Java Source and Target Level – the compiler source and target levels controlling the version of the language used and the version of the bytecode produced, also dictating the minimum version able to run the software

• Compatible Java Versions – the versions of Java deemed compatible¹ with the software

• Supported Java Versions – the versions of Java supported² to run the software

¹The term "compatible" here refers to the commitment by the project to ensure compatibility through testing and to treat any discovered incompatibilities as bugs.

...

We define three types of versions:

• Patch version - A software release that addresses bugs in the previous version. Patch versions are denoted by incrementing the PATCH component of the MAJOR.MINOR.PATCH version identifier.

• Minor version - A software release that addresses bugs and adds, but does not remove, functionality. Minor versions are denoted by incrementing the MINOR component of the MAJOR.MINOR.PATCH version identifier.

• Major version - A software release that makes significant changes and may add or remove functionality. Typically but not exclusively, removal of features occurs only after some period of deprecation in earlier releases. Major versions are denoted by incrementing the MAJOR component of the MAJOR.MINOR.PATCH version identifier.

Plugin Compatibility

As a general rule, the policy is designed to guarantee API (compile-time) compatibility for plugins and extensions developed for use with a given minor version with all subsequent patch and minor upgrades until the next major upgrade. Of course, a major upgrade doesn't guarantee breakage, but neither can compatibility be assumed.

...

For IdP V4.0 and later, we do not support any external code which relies on deriving classes which are subclasses of BaseContext. The motivation is that this restriction allows us to add methods to our context classes (which could break external code which implements methods with the same signature).

...

A patch version has the following general compatibility when compared with a previous version with the same minor version number:

• Java Source and Target Level: identical

• Compatible Java Versions: may add/deprecate, but not remove, versions

• Supported Java Versions: may add/deprecate, but not remove, versions

• Java API: identical

• 3rd Party Libraries: identical unless a library upgrade was required to address a bug affecting use of the product

• Configuration: identical

• Protocol Messages: wire-compatible

• Storage Formats (API): identical

• Storage Formats (non-API): may adjust in ways that are compatible with all patch versions with the same minor version number

The result of this is that upgrading/downgrading from one patch version to another generally will not require any change other than installing the version to be used, though it is advisable not to perform downgrades; preserving one's original configuration and restoring it is a better choice.

...

A minor version has the following compatibility when compared with a previous minor version with the same major version number:

• Java Source and Target Level: identical

• Compatible Java Versions: may add/deprecate, but not remove, versions

• Supported Java Versions: may add versions or remove deprecated versions

• Java API: may add/deprecate, but not remove, APIs

• 3rd Party Libraries: may add/upgrade, but not remove, libraries; upgrades to libraries must follow the Java API compatibility rules

• Configuration: may add/deprecate, but not remove, options/properties/beans/etc.

• Protocol Messages: may add, but not remove, new protocols/options; protocol implementations in common with previous minor versions remain wire-compatible

• Storage Formats (API): may add to, but not remove from, formats in ways that would not be expected to break standard tools interacting with the data

• Storage Formats (non-API): may change in ways that render older minor versions incapable of working with the data

The result of this is that upgrading from one minor version to another does not require any change other than installing the version to be used and updating the builds of any third-party plugins used. Existing configuration files will work unchanged, but may need to be modified to take advantage of new features. Downgrading to an older minor version may require removing configuration options introduced in newer versions.

...

A major version has the following compatibility when compared with another major version:

• Java Source and Target Level: may be different

• Compatible Java Versions: may add or remove versions

• Supported Java Versions: may add or remove versions

• Java API: may add/change/remove APIs

• 3rd Party Libraries: may add/upgrade/remove libraries

• Configuration Files: may add/change/remove options/properties/beans, and alter formats

• Protocol Messages: may add/change/remove protocols; protocol implementations in common with previous major versions remain wire-compatible

• Storage Formats (API): may be different

• Storage Formats (non-API): may be different

Example Compatibility Matrix