Return-Path: Delivered-To: apmail-apr-cvs-archive@apr.apache.org Received: (qmail 73974 invoked by uid 500); 10 May 2002 11:13:00 -0000 Mailing-List: contact cvs-help@apr.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Reply-To: dev@apr.apache.org Delivered-To: mailing list cvs@apr.apache.org Received: (qmail 73963 invoked by uid 500); 10 May 2002 11:13:00 -0000 Delivered-To: apmail-apr-site-cvs@apache.org Date: 10 May 2002 11:12:59 -0000 Message-ID: <20020510111259.74834.qmail@icarus.apache.org> From: gstein@apache.org To: apr-site-cvs@apache.org Subject: cvs commit: apr-site versioning.html index.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N gstein 02/05/10 04:12:59 Modified: . index.html Added: . versioning.html Log: Document how the APR projects will handle version numbering. Revision Changes Path 1.22 +5 -0 apr-site/index.html Index: index.html =================================================================== RCS file: /home/cvs/apr-site/index.html,v retrieving revision 1.21 retrieving revision 1.22 diff -u -r1.21 -r1.22 --- index.html 8 May 2002 21:12:20 -0000 1.21 +++ index.html 10 May 2002 11:12:59 -0000 1.22 @@ -81,6 +81,11 @@ You can find sample client/server programs which demonstrate APR concepts here.

+

+ We have written a document to explain the + version numbering concepts for the + libraries in the APR project. +

Mailing Lists

1.1 apr-site/versioning.html Index: versioning.html =================================================================== APR's Version Numbering

APR's Version Numbering

This document covers how the APR projects are versioned. Since the APR projects are libraries, it is very important to define a stable API for users of the libraries. However, we also need to move the libraries forward, technologically. To balance these two needs, a strict policy of versioning is required, which users can rely upon to understand the limitations, restrictions, and the changes that can occur from one release of APR to the next.

The Basics

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.

Source Compatibility

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 against previous minor versions.

Binary Compatibility

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.

Examples

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.

Strategy

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

Patch Versions

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 (with restrictions) replace 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.

New constants
Similar to functions, all of the original/old ocnstants 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. However, it is possible to add a new function with a new name, and use a macro to map the old function to the new function.

For example, let's say that in version 1.2.x, we had a function defined like this:

void some_function(const char *arg1);

In version 1.3.x, we want to add a parameter to the function, so we define the new function and map the old one using a macro:

void some_function2(const char *arg1, int arg2);
#define some_function(a) some_function2((a), 0)

Within the implementation, we would have the following code:

#undef some_function
void some_function(const char *arg1)
{
    some_function2(arg1, 0);
}

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 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.

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 functions
  • fold together macro-ized function replacements

Other Notes

It is expected that other libraries, besides those in the APR project, will want to use the above definitions of versioning. This is quite fine, and those libraries can simply reference this document. Its canonical location is:

http://apr.apache.org/versioning.html

It is also important to note that a library that has not reached 1.0.0 is not subject to the above guidelines. Before a 1.0 release, the API can and will be changing freely, without regard to the restrictions noted in this document.

Greg Stein
Last modified: Fri May 10 04:09:36 PDT 2002