Versions are denoted using a standard triplet of integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions are incompatible, large-scale upgrades of the API. MINOR versions retain source and binary compatibility with older minor versions, and changes in the PATCH level are perfectly compatible, forwards and backwards.

It is important to note that a library that has not reached 1.0.0 is not subject to the guidelines described in this document. Before a 1.0 release (version 0.x.y), the API can and will be changing freely, without regard to the restrictions detailed below.

We define "source compatible" to mean that an application will continue to build without error, and that the semantics will remain unchanged.

Applications that write against a particular version will remain source-compatible against later versions, until the major number changes. However, if an application uses an API which has become available in a particular minor version, it (obviously) will no longer build or operate against previous minor versions.

We define "binary compatible" to mean that a compiled application can be linked (possibly dynamically) against the library and continue to function properly.

Similar to source compatibility, an application that has been compiled against a particular version will continue to be linkable against later versions (unless the major number changes). It is possible that an application will not be able to successfully link against a previous minor version.

Here are some examples to demonstrate the compatibility:

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 different major versions is not guaranteed.
2.2.3	1.4.7	No Compatibility with different major versions is not guaranteed.

Note: while some of the cells say "no", it is possible that the versions may be compatible, depending very precisely upon the particular APIs used by the application.

This section details how we will build the code to meet the above requirements and guidelines.

Patch Version

To retain perfect source and binary compatibility, a patch release can only change function implementations. Changes to the API, to the signatures of public functions, or to the interpretation of function parameters is not allowed. Effectively, these releases are pure bug fix releases.

Minor Versions

Minor releases can introduce new functions, new symbolic and enumerated constants, and deprecate existing functions. New functions An application coded against an older minor release will still have all of its functions available with their original signatures. Once an application begins to use a new function, however, they will be unable to work against older minor versions. It is tempting to say that introducing new functions might create incompatibility across minor releases. If an application takes advantage of an API that was introduced in version 2.3 of a library, then it is not going to work against version 2.2. However, we have stated that an any application built against version 2.2 will continue to work for all 2.x releases. Thus, an application that states "requires 2.3 or later" is perfectly acceptable -- the user or administrator simply upgrades the installed library to 2.3. This is a safe operation and will not break any other application that was using the 2.2 library. In other words, yes an incompatibility arises by mandating that a specific version needs to be installed. But in practice, this will not be a problem since upgrading to newer versions is always safe. New constants Similar to functions, all of the original (old) constants will be available to an application. An application can then choose to use new constants to pick up new semantics and features. Replacing functions This gets a bit trickier. The original function must remain available at the link-level so that an application compiled against a minor version will continue to work with later minor versions. Further, if an application is designed to work with an earlier minor version, then we don't want to suddenly change the requirements for that application. This means that the headers cannot silently map an old function into a newer function, as that would turn an application, say, based on 1.2 into an application requiring the 1.4 or later release. This means that functions cannot truly be replaced. The new, alternate function can be made available in the header and applications can choose to use it (and become dependent upon the minor release where the function appears). It is possible to design a set of headers where a macro will always refer to the "latest" function available. Of course, if an application chooses to use this macro, then the resulting compiled-binary will be dependent upon whatever version it was compiled against. This strategy adds the new functionality for applications, yet retains the necessary source and binary compatibility for applications designed or built against previous minor releases. Constants (enumerated values and preprocessor macros) are not allowed to change since an older application will still be using them. Similarly, function signatures at the link-level may not change, so that support for older, compiled applications is maintained. Deprecating functions Since a function must remain available for applications coded against a previous minor release, it is only possible to "deprecate" a function. It cannot be removed from the headers (so that source compatibility is retained) and it cannot be removed from the library (so that binary compatibility is retained). If you deprecate a function in APR, please mark it as such in the function documentation, using the doxygen "deprecated" tag. Deprecated functions can only be removed in major releases. A deprecated function should remain available through the original header. The function prototype should remain in the same header, or if moved to a "deprecated functions" header, then the alternate header should be included by the original header. This requirement is to ensure that source compatibility is retained. Finally, if you are deprecating a function so that you can change the name of the function, please use the method described above under "Replacing functions", so that projects which use APR can retain binary compatibility. Note that all deprecated functions will be removed at the next major version bump.

Major Versions

Any kind of change can be made during a major version release. Particular types of changes that might occur: remove or change constants remove (deprecated) functions fold together macro-ized function replacements