Version Policy for Native/C++ Components

Version Numbers

The native/C++ components of Shibboleth and OpenSAML uses a standard triplet version format: MAJOR.MINOR.PATCH. Each component is an integer and is separated by a "." (period). When discussing a release we use the terms "patch release" to indicate a release where the PATCH component has been incremented, "minor release" to indicate a release where the MINOR component has been incremented, and a "major release" to indicate a release where the MAJOR component has been incremented.

The overall package is versioned in this manner, but each library that exports public APIs is also independently versioned the same way. Library versions MAY change independently of both each other and the overall package version. Version macros are provided to enable autoconf and source code constraints.

Version Compatibility

Compatibility is defined as follows. A backwards compatible release is a release that may be used in place of an older release without modification of the software or configuration (i.e. it is possible to upgrade without changing anything). A forwards compatible release is a release that may be used in place of a newer release without modification of the software or configuration (i.e. it is possible to downgrade without changing anything).

Compatibility is tracked in four areas:

• Binary Compatibility (library linkage)

• Source Compatibility (public APIs: classes, methods, constants, etc.)

• Configuration files

• Protocol or on-the-wire messages and behavior

Versioning Strategy

This section details the requirements for each release type.

Patch Release

A patch release MUST maintain perfect binary, source, configuration, and protocol compatibility. In other words, the release is both forwards and backwards compatible. Effectively, these releases are pure bug fix releases. Generally a patch release will not include anything other than patch releases of the libraries it depends on.

Minor Release

A minor version MAY introduce new features and APIs and may deprecate, but MUST NOT remove, old APIs. Minor versions are backwards and forward compatible with respect to protocol behavior. With respect to source and configuration, they are backward but not necessarily forward compatible. This is because new features/configuration options may be added in a minor release and older versions of the software may not properly deal with these changes if a downgrade were attempted. Effectively, these are feature addition releases.

A minor release does NOT generally provide binary compatibility for extensions or package components that depend on it.

Major Release

A major version MAY make any type of change to protocols, APIs, and configuration. As such, neither backwards nor forwards compatibility is guaranteed. However, particularly from a configuration and protocol perspective, we do not imply that breakage itself is likely. As a mature software stack relying on a mature standard (SAML 2.0), signficant backward compatibility should be expected, even across major releases, with the exception of deprecated features or options. We reserve the right to make breaking changes, but do not necessarily seek to do so.

Extensions

Because C++ supports polymorphism, but is not an interpreted language, API additions frequently break binary compatibility by altering virtual function tables. The effort involved in preventing this is not worth the benefit, so meaningful changes to any header file are assumed to break binary compatibility, and therefore occur only during minor or major releases. Significantly, a minor release is assumed to require recompiling and relinking any software that depends on the library in question. A minor release is guaranteed to provide backward source compatibility, so rebuilding should be successful in such cases.

When such changes occur, the library name or soname will change according to standard practices, and extensions should not need to take any special steps to ensure that an incompatible library version isn't accidentally used.