Java Products' Version Policy

This document sets out the policy used for versioning the Shibboleth Java products. It defines classifications of releases, indicates how they are identified, and the level of compatibility between them.

Terminology

Version Numbers

The Shibboleth Java products use a standard triplet format for their version designators: MAJOR.MINOR.PATCH where each component is an integer and is separated by a "." (period).

Version Types

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 internal changes to the product and may add or remove functionality. Major versions are denoted by incrementing the MAJOR component of the MAJOR.MINOR.PATCH version identifier.

Compatibility

Four types of compatibility are tracked across product versions:

• Public APIs - methods/classes which may be used by extension developers including people writing JSR-223 scripts
• 3rd party libraries - 3rd party methods and classes upon which our product relies
• Configuration Files
• Protocol messages - the messages exchanged between the product and its communication partner

Patch Version Compatibility

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

• Public API: identical
• 3rd Party Libraries: identical unless a library upgrade was required to address a bug corrected by this version
• Configuration Files: identical
• Protocol Messages: identical

The result of this is that upgrading/downgrading from one patch version to another does not require any change other than installing the version to be used.

Minor Version Compatibility

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

• Public API: may add/deprecate, but not remove, APIs
• 3rd Party Libraries: may add/upgrade, but not remove, libraries
• Configuration Files: may add/deprecate, but not remove, options
• Protocol Messages: may add, but not remove, new protocols/options

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. Existing configuration files will work unchanged, but may need to be modified to take advantage of new features. Downgrading to an older minor version requires removing configuration options introduced in newer versions.

Major Version Compatibility

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

• Public API: may add/edit/remove APIs
• 3rd Party Libraries: may add/edit/remove libraries
• Configuration Files: may add/edit/remove options
• Protocol Messages: may add/edit/remove protocols but protocols implementations in common with previous major versions will remain wire-compatible

Example Compatibility Matrix