apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gst...@apache.org
Subject cvs commit: apr-site versioning.html index.html
Date Fri, 10 May 2002 11:12:59 GMT
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>
  	    &nbsp;&nbsp;&nbsp;&nbsp;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:gstein@lyra.org">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>
  
  
  

Mime
View raw message