About Versioning

The XStream project follows strict rules that govern its use of version numbers. The version number of a release indicates how that release is compatible with previous and future releases.

Version numbers have the form major.minor.patch. A major version identifies the product stage of the project. Two libraries with different major version are designed to work together in the same application. This implies a major change in the API - either by not sharing the same types or using a different package name.

The minor version number identifies the API version. A release that changes the API in a way that breaks backwards compatibility will increment the minor version number and reset the patch version to zero. The patch version number identifies the backwards compatible revision of the API. A change in the minor version will still be mostly backward compatible, but may need some compatibility settings or slight migration adjustments. The patch version number identifies revisions that do not change the API although new API elements may occur or existing API may be deprecated to prepare users for the next release with a change in the minor version. A release that fixes bugs or refactors implementation details without changing the API will have the same minor and major versions as the previous release and increment the patch number.

A hypothetical example:

1.0.0	First release
1.0.1	Improves Javadoc comments, fixes bug
1.1.0	Adds new API elements, may cause some migration
1.1.1	Adds new API elements, deprecates some API elements
1.1.2	Fixes bugs
1.2.0	Adds new API, needs some migration effort and removes deprecated elements
2.0.0	Complete API redesign, can be used simultanly with 1.x series.
2.0.1	Deprecates API, fixes bugs
2.1.0	Adds new API elements
etc.	etc.

Release Candidates

Before a new major or minor release, XStream will make release candidate (RC) packages available so that users can test them against their own code. There will be one or more release candidates given the version major.minor.0 RCn, where the major and minor version numbers identify the upcoming release and RC1 identifies the first candidate release, RC2 the second, and so on.

A release candidate does not guarantee backward compatibility with new API features introduced by any previous RC of the same upcoming version. A major version RC can change/remove API features introduced in a previous RC for the same major version; a minor version RC can change API features introduced by any previous RC of the same upcoming minor version but guarantees backward compatibility with the previous minor version.

Development Snapshots

During development, the the developers may publish snapshot packages from time to time. These are not guaranteed to be complete: Although the unit tests will all pass the snapshot will probably contain failing acceptance tests that describe planned or requested features that have not yet been implemented. Snapshots are identified by the UTC time at which the package was built. The timestamp has the form VERSION-YYYYMMDD.hhmmss-n, where VERSION is the upcoming version, YYYY is the (four-digit) year, MM the month, DD the day, hh the hour, mm the minute, ss the second and n a sequential number.

Internal Classes

Many classes are for internal use only and not designed to be used by end users. These are exempt from the versioning rules above.

Such classes are clearly marked as internal in the source code headers and are excluded from the published JavaDoc.

Versioning and Deprecation

A patch release might deprecate some API features. Deprecated features will not actually be removed until the next minor release. A release will never remove API features that have not been deprecated in a previous release.