Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

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 addresses bugs in the previous version. Patch versions are denoted by the 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 the incrementing the MINOR component of the MAJOR.MINOR.PATCH version identifier.
  • Major version - A software releases that makes significant internal changes to the product and may add or remove functionality. Minor versions are denoted by the 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
  • 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 Release Compatibility

A patch release fixes bugs. It neither adds nor removes functionality.

A patch release has the following compatibility when compared with a previous patch release:

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

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

Minor Release Stream Compatibility

A minor release stream introduces new features.

A minor release stream has the following compatibility when compared with a previous minor release stream:

  • 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 release 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 release requires removing configuration options introduced in newer releases.

Major Release Stream Compatibility

A major release stream of the software makes fundamental change to the product (e.g., new architecture, new configuration mechanism, removal of old/broken APIs).

A major release stream has the following compatibility when compared with a major release stream:

  • 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 minor releases will remain wire-compatible

Example Compatibility Matrix

Original Version

New Version

Compatible?

2.2.3

2.2.4

Yes
Compatibility across patch versions is guaranteed.

2.2.3

2.2.1

Yes
Compatibility across patch versions is guaranteed.

2.2.3

2.3.1

Yes
Compatibility with later minor versions is guaranteed.

2.2.3

2.1.7

No
Compatibility with prior minor versions is not guaranteed.

2.2.3

3.0.0

No
Compatibility with prior major versions is not guaranteed.

2.2.3

1.4.7

No
Compatibility with prior major versions is not guaranteed.

  • No labels