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 <a href="apr2_0intro/">here.</a>
</p>
+ <p>
+ We have written a document to explain the
+ <a href="versioning.html">version numbering concepts</a> for the
+ libraries in the APR project.
+ </p>
<h3>Mailing Lists</h3>
<p>
1.1 apr-site/versioning.html
Index: versioning.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>APR's Version Numbering</title>
</head>
<body>
<h1>APR's Version Numbering</h1>
<p>
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.
</p>
<ul>
<li><a href="#basics">The Basics</a></li>
<li><a href="#source">Source Compatibility</a></li>
<li><a href="#binary">Binary Compatibility</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#stategy">Strategy</a></li>
<li><a href="#notes">Other Notes</a></li>
</ul>
<hr />
<h2><a name="basics">The Basics</a></h2>
<p>
Versions are denoted using a standard triplet of integers:
<tt><strong>MAJOR.MINOR.PATCH</strong></tt>. The basic intent is
that <tt><strong>MAJOR</strong></tt> versions are incompatible,
large-scale upgrades of the API. <tt><strong>MINOR</strong></tt>
versions retain source and binary compatibility with older minor
versions, and changes in the <tt><strong>PATCH</strong></tt>
level are perfectly compatible, forwards and backwards.
</p>
<h2><a name="source">Source Compatibility</a></h2>
<p>
We define "source compatible" to mean that an application will
continue to build without error, and that the semantics will
remain unchanged.
</p>
<p>
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.
</p>
<h2><a name="binary">Binary Compatibility</a></h2>
<p>
We define "binary compatible" to mean that a compiled
application can be linked (possibly dynamically) against the
library and continue to function properly.
</p>
<p>
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.
</p>
<h2><a name="examples">Examples</a></h2>
<p>
Here are some examples to demonstrate the compatibility:
</p>
<table>
<tr>
<th>Original Version</th>
<th>New Version</th>
<th>Compatible?</th>
</tr>
<tr valign="top" bgcolor="#e0e0e0">
<td>2.2.3</td>
<td>2.2.4</td>
<td>
Yes
<br>
<font size="-1">Compatibility across patch versions is
guaranteed.</font>
</td>
</tr>
<tr valign="top">
<td>2.2.3</td>
<td>2.2.1</td>
<td>
Yes
<br>
<font size="-1">Compatibility across patch versions is
guaranteed.</font>
</td>
</tr>
<tr valign="top" bgcolor="#e0e0e0">
<td>2.2.3</td>
<td>2.3.1</td>
<td>
Yes
<br>
<font size="-1">Compatibility with later minor versions is
guaranteed.</font>
</td>
</tr>
<tr valign="top">
<td>2.2.3</td>
<td>2.1.7</td>
<td>
No
<br>
<font size="-1">Compatibility with prior minor versions is
not guaranteed.</font>
</td>
</tr>
<tr valign="top" bgcolor="#e0e0e0">
<td>2.2.3</td>
<td>3.0.0</td>
<td>
No
<br>
<font size="-1">Compatibility with different major versions
is not guaranteed.</font>
</td>
</tr>
<tr valign="top">
<td>2.2.3</td>
<td>1.4.7</td>
<td>
No
<br>
<font size="-1">Compatibility with different major versions
is not guaranteed.</font>
</td>
</tr>
</table>
<p>
Note: while some of the cells say "no", it is <em>possible</em>
that the versions may be compatible, depending very precisely
upon the particular APIs used by the application.
</p>
<h2><a name="strategy">Strategy</a></h2>
<p>
This section details how we will build the code to meet the
above requirements and guidelines.
</p>
<h3>Patch Versions</h3>
<p>
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 <strong>not
allowed</strong>. Effectively, these releases are pure bug fix
releases.
</p>
<h3>Minor Versions</h3>
<p>
Minor releases can introduce new functions, new symbolic and
enumerated constants, and (with restrictions) replace existing
functions.
</p>
<dl>
<dt>New functions</dt>
<dd>
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.
<p></p>
</dd>
<dt>New constants</dt>
<dd>
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.
<p></p>
</dd>
<dt>Replacing functions</dt>
<dd>
This gets a bit trickier. The original function
<strong>must</strong> 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
<em>is</em> possible to add a new function with a new name,
and use a macro to map the old function to the new function.
<p>
For example, let's say that in version 1.2.x, we had a
function defined like this:
</p>
<blockquote>
<tt>void some_function(const char *arg1);</tt>
</blockquote>
<p>
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:
</p>
<blockquote>
<tt>
void some_function2(const char *arg1, int arg2);
<br>
#define some_function(a) some_function2((a), 0)
</tt>
</blockquote>
<p>
Within the implementation, we would have the following code:
</p>
<blockquote>
<tt>
#undef some_function
<br>
void some_function(const char *arg1)
<br>
{
<br>
some_function2(arg1, 0);
<br>
}
</tt>
</blockquote>
<p>
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.
</p>
<p>
Constants are not allowed to <em>change</em> 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.
</p>
</dd>
</dl>
<h3>Major Versions</h3>
<p>
Any kind of change can be made during a major version release.
Particular types of changes that might occur:
</p>
<ul>
<li>remove or change constants</li>
<li>remove functions</li>
<li>fold together macro-ized function replacements</li>
</ul>
<h2><a name="notes">Other Notes</a></h2>
<p>
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:
</p>
<blockquote>
http://apr.apache.org/versioning.html
</blockquote>
<p>
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.
</p>
<hr />
<address><a href="mailto:[EMAIL PROTECTED]">Greg Stein</a></address>
<!-- Created: Thu May 2 16:58:05 PDT 2002 -->
<!-- hhmts start -->
Last modified: Fri May 10 04:09:36 PDT 2002
<!-- hhmts end -->
</body>
</html>
