apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jerenkra...@apache.org
Subject cvs commit: apr-site/xdocs guidelines.xml versioning.xml guidelines.html versioning.html
Date Fri, 26 Sep 2003 04:47:27 GMT
jerenkrantz    2003/09/25 21:47:27

  Modified:    docs     guidelines.html versioning.html
  Added:       xdocs    guidelines.xml versioning.xml
  Removed:     xdocs    guidelines.html versioning.html
  Log:
  Rewrite guidelines and versioning to use the template.
  
  Revision  Changes    Path
  1.2       +214 -163  apr-site/docs/guidelines.html
  
  Index: guidelines.html
  ===================================================================
  RCS file: /home/cvs/apr-site/docs/guidelines.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -u -r1.1 -r1.2
  --- guidelines.html	26 Sep 2003 04:00:22 -0000	1.1
  +++ guidelines.html	26 Sep 2003 04:47:27 -0000	1.2
  @@ -1,169 +1,220 @@
  -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html>
  -  <head>
  -    <title>APR Project Guidelines</title>
  -  </head>
  -
  -  <body>
  -    <h1>APR Project Guidelines</h1>
  -
  -    <p>
  -      This page describes the procedures and guidelines used by the
  -      APR Project.
  -    </p>
  -    <p>
  -      <i>this is an initial draft</i>
  -    </p>
  -
  -    <h2>Commit Access</h2>
  -    <p>
  -      Commit access will be somewhere between the "lengthy" process of
  -      new-httpd, and the more "open" process in Subversion.
  -    </p>
  -    <p>
  -      Specifically, if a person submits several reasonable patches
  -      that apply well and follow the general guidelines, and that
  -      person appears to "get the process", then they will be provided
  -      commit access.
  -    </p>
  -    <p>
  -      This policy generally depends upon the fact that we can always
  -      recover from problematic committers (since we use source
  -      control). The PMC also reserves the right to suspend commit
  -      privileges, if other APR members end up spending too much time
  -      dealing with problematic commits.
  -    </p>
  -
  -    <h2>Change Process</h2>
  -    <p>
  -      Most changes (bug fixes and minor, commonsense feature adds) do
  -      not require review.  Developers are encouraged to request review
  -      for:
  -    </p>
  -    <ul>
  -      <li>
  -	Large changes affecting many files
  -      </li>
  -      <li>
  -	Changes to interfaces
  -      </li>
  -      <li>
  -	Changes that commit APR to one option out of an exclusive set
  -      </li>
  -      <li>
  -	Any change the developer wants a second (or Nth) opinion on
  -      </li>
  -    </ul>
  -    <p>
  -      Anyone may retroactively cause someone's change to be reviewed
  -      by requesting review after it was committed, and at their
  -      discretion may revert the change until it is approved.
  -    </p>
  -    <p>
  -      The above process is called "Commit Then Review" (or CTR). As of
  -      this time, the group does not see a need to ever use a "Review
  -      Then Commit" (RTC) process.
  -    </p>
  -
  -    <h2>PMC Membership</h2>
  -    <p>
  -      PMC membership is attained through a "consensus approval"
  -      process according to the
  -      <a href="http://httpd.apache.org/dev/guidelines.html">standard ASF
  -	guidelines</a>.  The voters are the existing PMC members.
  -    </p>
  -    <p>
  -      The general policy is to accept committers who have demonstrated
  -      longevity in dev/doc/admin ability and interest in the APR
  -      project.
  -    </p>
  -
  -    <h2>Decision Making: Consensus and Voting</h2>
  -    <dl>
  + <head>
  +  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  +       <meta name="author" content="APR Developers" /><meta name="email" content="dev@apr.apache.org" />
  +    <title>Project Guidelines - The Apache Portable Runtime Project</title>
  + </head>
  + <body bgcolor="#ffffff" text="#000000" link="#525D76">
  +<p><a href="/"><img src="./images/apr_logo_wide.png" alt="The Apache Portable Runtime Project" border="0"/></a></p>
  + <table border="0" width="100%" cellspacing="4">
  +   <tr>
  +    <!-- LEFT SIDE NAVIGATION -->
  +    <td valign="top" nowrap="nowrap">
  +           <p><b>Essentials</b></p>
  +    <menu compact="compact">
  +          <li><a href="http://www.apache.org/LICENSE.txt">License</a></li>
  +        </menu>
  +      <p><b>Subprojects</b></p>
  +    <menu compact="compact">
  +          <li>APR</li>
  +          <li>APR-util</li>
  +          <li>APR-iconv</li>
  +        </menu>
  +      <p><b>Download!</b></p>
  +    <menu compact="compact">
  +          <li><a href="http://www.apache.org/dyn/closer.cgi/apr/">from a mirror</a></li>
  +        </menu>
  +      <p><b>Get Involved</b></p>
  +    <menu compact="compact">
  +          <li><a href="anoncvs.txt">CVS</a></li>
  +          <li><a href="http://cvs.apache.org/snapshots/apr/">Snapshots</a></li>
  +          <li><a href="compiling_win32.html">Build on Win32</a></li>
  +          <li><a href="compiling_unix.html">Build on Unix</a></li>
  +        </menu>
  +      <p><b>Guidelines</b></p>
  +    <menu compact="compact">
  +          <li><a href="guidelines.html">Project Guidelines</a></li>
  +          <li><a href="patches.html">Contributing</a></li>
  +          <li><a href="versioning.html">Version Numbers</a></li>
  +        </menu>
  +    </td>
  +    <!-- RIGHT SIDE INFORMATION -->
  +    <td align="left" valign="top">
  +                <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>APR Project Guidelines</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>This page describes the procedures and guidelines used by the APR
  +Project.</p>
  +<p><i>this is an initial draft</i></p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Commit Access</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Commit access will be somewhere between the "lengthy" process of httpd,
  +and the more "open" process in Subversion.</p>
  +<p>Specifically, if a person submits several reasonable patches that apply
  +well and follow the general guidelines, and that person appears to "get the
  +process", then they will be provided commit access.</p>
  +<p>This policy generally depends upon the fact that we can always recover
  +from problematic committers (since we use source control). The PMC also
  +reserves the right to suspend commit privileges, if other APR members end up
  +spending too much time dealing with problematic commits.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Change Process</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Most changes (bug fixes and minor, commonsense feature adds) do not
  +require review.  Developers are encouraged to request review for:</p>
  +<ul>
  +  <li>Large changes affecting many files</li>
  +  <li>Changes to interfaces</li>
  +  <li>Changes that commit APR to one option out of an exclusive set</li>
  +  <li>Any change the developer wants a second (or Nth) opinion on</li>
  +</ul>
  +<p>Anyone may retroactively cause someone's change to be reviewed by
  +requesting review after it was committed, and at their discretion may
  +revert the change until it is approved.</p>
  +<p>The above process is called "Commit Then Review" (or CTR). As of
  +this time, the group does not see a need to ever use a "Review
  +Then Commit" (RTC) process.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>PMC Membership</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>PMC membership is attained through a "consensus approval" process
  +according to the <a href="http://httpd.apache.org/dev/guidelines.html">standard ASF guidelines</a> (as set out by HTTP Server).  The voters are the
  +existing PMC members.</p>
  +<p>The general policy is to accept committers who have demonstrated
  +longevity in dev/doc/admin ability and interest in the APR project.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Decision Making: Consensus and Voting</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<dl>
         <dt><strong>NOTE:</strong></dt>
         <dd>
  -	The following text describes the precise rules and procedure
  -	for voting and decision making. In general, the behavior
  -	embodied in these rules is part of the "gestalt" of the group,
  -	and the formal use of these processes is not required.
  +  The following text describes the precise rules and procedure
  +  for voting and decision making. In general, the behavior
  +  embodied in these rules is part of the "gestalt" of the group,
  +  and the formal use of these processes is not required.
         </dd>
       </dl>
  -    <p>
  -      Whenever possible, decisions are made by consensus.  Consensus
  -      is reached when both the following conditions are met: a
  -      committer indicates that consensus has been reached, and no
  -      committer claims that consensus has not yet been reached.  On
  -      any given issue, there is a 72-hour window after a claim of
  -      consensus before the consensus is considered binding, to give
  -      people time to react.
  -    </p>
  -    <p>
  -      [ gjs: changes can always be reverted, so why a window? and why
  -      is a decision ever "binding"? ]
  -      <br>
  -      [ gjs: need some text that describes the use of +/- 0/1 for
  -      talking about changes and their use in deciding whether
  -      consensus has been reached ]
  -    </p>
  -    <p>
  -      For decisions on which consensus is not reachable or is not
  -      attempted, the group votes, using approval voting:
  -    </p>
  -    <blockquote>
  -      <p>
  -	Each voter is allowed to cast a single vote for each of as
  -	many of the ballot choices as desired -- that is, the voter
  -	votes for all choices of which the voter "approves."  Each
  -	vote is one of:
  -      </p>
  -      <p>
  -	+1 : Yes, agree that the choice should be performed.
  -	<br>
  -	+0 : Seems fine, but I can live without it
  -	<br>
  -	-0 : Doesn't seem right, but I won't argue against it
  -	<br>
  -	-1 : No, I am against this choice being performed.
  -      </p>
  -    </blockquote>
  -    <p>
  -      Choices receiving positive totals may be performed.
  -    </p>
  -    <p>
  -      When the set of ballot choices cannot be agreed on, the PMC
  -      chair decides the set.  If the question of whether consensus has
  -      been reached or not is undecidable (this "can't happen", but who
  -      knows), the chair decides whether or not it has been reached.
  -    </p>
  -    <p>
  -      Changes to these decision-making procedures may be made by
  -      consensus.  But, if such a change does reach the voting stage,
  -      then positive votes must outnumber negative votes by a
  -      two-to-one ratio, or greater, for the change to take effect.
  -    </p>
  -
  -    <h3>Veto as a vote</h3>
  -    <p>
  -      A voter explicitly stating that they veto the decision,
  -      providing a justification of their veto is sufficient to table a
  -      vote until the issue is addressed and the vetoer or those who
  -      agreed concur that the the issue is addressed.
  -    </p>
  -
  -    <h3>Voting Procedure Technicalities</h3>
  -    <p>
  -      Votes are tallied in the <tt>STATUS</tt> file, adjacent to the
  -      action item under vote.  All votes must be either sent to the
  -      mailing list or added directly to the <tt>STATUS</tt> file entry
  -      for that action item.
  -    </p>
  -
  -    <hr>
  -    <address><a href="mailto:gstein@lyra.org">Greg Stein</a></address>
  -<!-- Created: Fri Nov 24 16:27:22 PST 2000 -->
  -<!-- hhmts start -->
  -Last modified: Fri Nov 24 16:42:42 PST 2000
  -<!-- hhmts end -->
  -  </body>
  +<p>Whenever possible, decisions are made by consensus.  Consensus is reached
  +when both the following conditions are met: a committer indicates that
  +consensus has been reached, and no committer claims that consensus has not yet
  +been reached.  On any given issue, there is a 72-hour window after a claim of
  +consensus before the consensus is considered binding, to give people time to
  +react.</p>
  +<p>
  +[ gjs: changes can always be reverted, so why a window?
  +  and why is a decision ever "binding"? ]
  +<br />
  +[ gjs: need some text that describes the use of +/- 0/1 for
  +  talking about changes and their use in deciding whether
  +  consensus has been reached ]
  +</p>
  +<p>For decisions on which consensus is not reachable or is not attempted,
  +the group votes, using approval voting:</p>
  +<blockquote>
  +
  +<p>Each voter is allowed to cast a single vote for each of as many of the
  +ballot choices as desired -- that is, the voter votes for all choices of which
  +the voter "approves."  Each vote is one of: </p>
  +
  +<ul>
  +  <li>+1 : Yes, agree that the choice should be performed.</li>
  +  <li>+0 : Seems fine, but I can live without it</li>
  +  <li>-0 : Doesn't seem right, but I won't argue against it</li>
  +  <li>-1 : No, I am against this choice being performed.</li>
  +</ul>
  +
  +</blockquote>
  +<p>Choices receiving positive totals may be performed.</p>
  +<p>When the set of ballot choices cannot be agreed on, the PMC chair decides
  +the set.  If the question of whether consensus has been reached or not is
  +undecidable (this "can't happen", but who knows), the chair decides whether or
  +not it has been reached.</p>
  +<p>Changes to these decision-making procedures may be made by consensus.  But,
  +if such a change does reach the voting stage, then positive votes must
  +outnumber negative votes by a two-to-one ratio, or greater, for the change to
  +take effect.</p>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Veto as a vote</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>A voter explicitly stating that they veto the decision, providing a
  +justification of their veto is sufficient to table a vote until the issue is
  +addressed and the vetoer or those who agreed concur that the the issue is
  +addressed.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Voting Procedure Technicalities</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Votes are tallied in the <tt>STATUS</tt> file, adjacent to the action item
  +under vote.  All votes must be either sent to the mailing list or added
  +directly to the <tt>STATUS</tt> file entry for that action item.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +  </blockquote>
  + </td></tr>
  +</table>
  +         </td>
  +   </tr>
  +   <!-- FOOTER -->
  +   <tr><td colspan="2"><hr noshade="noshade" size="1"/></td></tr>
  +   <tr><td colspan="2" align="center">
  +        <font size="-1">
  +         <em>Copyright &#169; 1999-2003, The Apache Software Foundation</em>
  +        </font>
  +       </td>
  +   </tr>
  +  </table>
  + </body>
   </html>
  -
  
  
  
  1.2       +525 -475  apr-site/docs/versioning.html
  
  Index: versioning.html
  ===================================================================
  RCS file: /home/cvs/apr-site/docs/versioning.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -u -r1.1 -r1.2
  --- versioning.html	26 Sep 2003 04:00:22 -0000	1.1
  +++ versioning.html	26 Sep 2003 04:47:27 -0000	1.2
  @@ -1,192 +1,238 @@
  -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  +               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <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="#strategy">Strategy</a></li>
  -      <li><a href="#vsncheck">Version Checking</a></li>
  -      <li><a href="#parallel">Parallel Installation</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>
  -    <p>
  -      It is important to note that a library that has not reached
  -      1.0.0 is <strong>not</strong> subject to the guidelines
  -      described in this document. Before a 1.0 release (version
  -      0.x.y), the API <em>can</em> and <em>will</em> be changing
  -      freely, without regard to the restrictions detailed below.
  -    </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 or operate 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 deprecate existing functions.
  -    </p>
  -    <dl>
  + <head>
  +  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  +       <meta name="author" content="APR Developers" /><meta name="email" content="dev@apr.apache.org" />
  +    <title>Versioning Numbering Concepts - The Apache Portable Runtime Project</title>
  + </head>
  + <body bgcolor="#ffffff" text="#000000" link="#525D76">
  +<p><a href="/"><img src="./images/apr_logo_wide.png" alt="The Apache Portable Runtime Project" border="0"/></a></p>
  + <table border="0" width="100%" cellspacing="4">
  +   <tr>
  +    <!-- LEFT SIDE NAVIGATION -->
  +    <td valign="top" nowrap="nowrap">
  +           <p><b>Essentials</b></p>
  +    <menu compact="compact">
  +          <li><a href="http://www.apache.org/LICENSE.txt">License</a></li>
  +        </menu>
  +      <p><b>Subprojects</b></p>
  +    <menu compact="compact">
  +          <li>APR</li>
  +          <li>APR-util</li>
  +          <li>APR-iconv</li>
  +        </menu>
  +      <p><b>Download!</b></p>
  +    <menu compact="compact">
  +          <li><a href="http://www.apache.org/dyn/closer.cgi/apr/">from a mirror</a></li>
  +        </menu>
  +      <p><b>Get Involved</b></p>
  +    <menu compact="compact">
  +          <li><a href="anoncvs.txt">CVS</a></li>
  +          <li><a href="http://cvs.apache.org/snapshots/apr/">Snapshots</a></li>
  +          <li><a href="compiling_win32.html">Build on Win32</a></li>
  +          <li><a href="compiling_unix.html">Build on Unix</a></li>
  +        </menu>
  +      <p><b>Guidelines</b></p>
  +    <menu compact="compact">
  +          <li><a href="guidelines.html">Project Guidelines</a></li>
  +          <li><a href="patches.html">Contributing</a></li>
  +          <li><a href="versioning.html">Version Numbers</a></li>
  +        </menu>
  +    </td>
  +    <!-- RIGHT SIDE INFORMATION -->
  +    <td align="left" valign="top">
  +                <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>APR's Version Numbering</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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="#strategy">Strategy</a></li>
  +  <li><a href="#vsncheck">Version Checking</a></li>
  +  <li><a href="#parallel">Parallel Installation</a></li>
  +  <li><a href="#notes">Other Notes</a></li>
  +</ul>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="basics"><strong>The Basics</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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>
  +<p> It is important to note that a library that has not reached 1.0.0 is
  +<strong>not</strong> subject to the guidelines described in this document.
  +Before a 1.0 release (version 0.x.y), the API <em>can</em> and <em>will</em> be
  +changing freely, without regard to the restrictions detailed below.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="source"><strong>Source Compatibility</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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 or operate
  +against previous minor versions.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="binary"><strong>Binary Compatibility</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="examples"><strong>Examples</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Here are some examples to demonstrate the compatibility:</p>
  +<font color="#000000" size="-1" face="arial,helvetica,sanserif">
  +<table width="100%">
  +  <tr>
  +    <th bgcolor="#039acc">Original Version</th>
  +    <th bgcolor="#039acc">New Version</th>
  +    <th bgcolor="#039acc">Compatible?</th>
  +  </tr>
  +  <tr valign="top" bgcolor="#e0e0e0">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">2.2.4</td>
  +    <td bgcolor="#a0ddf0">Yes<br /><font size="-1">Compatibility across patch versions is guaranteed.</font>
  +    </td>
  +  </tr>
  +  <tr valign="top">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">2.2.1</td>
  +    <td bgcolor="#a0ddf0">Yes<br /><font size="-1">Compatibility across patch versions is guaranteed.</font>
  +    </td>
  +  </tr>
  +  <tr valign="top" bgcolor="#e0e0e0">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">2.3.1</td>
  +    <td bgcolor="#a0ddf0">Yes<br /><font size="-1">Compatibility with later minor versions is guaranteed.</font>
  +    </td>
  +  </tr>
  +  <tr valign="top">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">2.1.7</td>
  +    <td bgcolor="#a0ddf0">No<br /><font size="-1">Compatibility with prior minor versions is not guaranteed.</font>
  +    </td>
  +  </tr>
  +  <tr valign="top" bgcolor="#e0e0e0">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">3.0.0</td>
  +    <td bgcolor="#a0ddf0">No<br /><font size="-1">Compatibility with different major versions is not guaranteed.</font>
  +    </td>
  +  </tr>
  +  <tr valign="top">
  +    <td bgcolor="#a0ddf0">2.2.3</td>
  +    <td bgcolor="#a0ddf0">1.4.7</td>
  +    <td bgcolor="#a0ddf0">No<br /><font size="-1">Compatibility with different major versions is not guaranteed.</font>
  +    </td>
  +  </tr>
  +</table>
  +</font>
  +<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>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="strategy"><strong>Strategy</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>This section details how we will build the code to meet the above
  +requirements and guidelines.</p>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Patch Version</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Minor Versions</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Minor releases can introduce new functions, new symbolic and enumerated
  +constants, and deprecate 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>
  -          It is tempting to say that introducing new functions might
  +
  +      <dd><p>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>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
  @@ -196,298 +242,302 @@
             "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.
  -        </p>
  -        <p>
  -          In other words, yes an incompatibility arises by mandating
  +          application that was using the 2.2 library.</p>
  +
  +          <p>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.
  -        </p>
  -      </dd>
  -      
  +          newer versions is always safe.</p>
  +        </dd>
  +
         <dt>New constants</dt>
  -      <dd>
  -	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.
  -	<p></p>
  -      </dd>
  -      
  +      <dd>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.</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. Further, if an
  -	application is <em>designed</em> to work with an earlier minor
  -	verison, 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.
  -	
  -	<p>
  -	  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).
  -	</p>
  -	<p>
  -	  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.
  -	</p>
  -	<p>
  -	  Constants (enumerated values and preprocessor macros) are
  -	  <strong>not</strong> 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.
  -	</p>
  +      <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. Further, if an application is
  +          <em>designed</em> 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.
  +
  +          <p>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).</p>
  +
  +          <p>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.</p>
  +
  +          <p>Constants (enumerated values and preprocessor macros) are
  +          <strong>not</strong> 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.</p>
         </dd>
  -      
  -      <dt>Deprecating functions</dt>
  -      <dd>
  -	Since a function must remain available for applications coded
  -	against a previous minor release, it is only possible to
  -	"<em>deprecate</em>" a function. It <strong>cannot</strong> 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).
  -
  -	<p>
  -	  If you deprecate a function in APR, please mark it as such
  -	  in the function documentation, using the doxygen
  -	  "<code>\deprecated</code>" tag.  Deprecated functions can
  -	  only be removed in major releases.
  -	</p>
  -	<p>
  -	  A deprecated function should remain available
  -	  <em>through</em> the original header. The function prototype
  -	  should remain in the same header, or if moved to a
  -	  "deprecated functions" header, then the altnerate header
  -	  should be included by the original header. This requirement
  -	  is to ensure that source compatibility is retained.
  -	</p>
  -	<p>
  -	  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.
  -	</p>
  -	<p>
  -	  Note that all deprecated functions will be removed at the
  -	  next major version bump.
  -	</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 (deprecated) functions</li>
  -      <li>fold together macro-ized function replacements</li>
  -    </ul>
  -
  -    <h2><a name="vsncheck">Version Checking</a></h2>
  -    <p>
  -      In many cases, the user of a library will need to check the
  -      version that they are compiling against, or that is being used
  -      at runtime. Because of the strict rules of source and binary
  -      compatibility, these checks can be simpler and more complicated
  -      depending on what is needed.
  -    </p>
  -
  -    <h3>Compile-time Checks</h3>
  -    <p>
  -      Libraries should make their version number available as
  -      compile-time constants. For example:
  -    </p>
  -    <blockquote>
  -      <tt>
  -        #define FOO_MAJOR_VERSION 1
  -        <br>
  -        #define FOO_MINOR_VERSION 4
  -        <br>
  -        #define FOO_PATCH_VERSION 0
  -      </tt>
  -    </blockquote>
  -    <p>
  -      The above symbols are the minimum required for this
  -      specification.
  -    </p>
  -    <p>
  -      An application that desires, at compile-time, to decide on
  -      whether and how to use a particular library feature needs to
  -      only check two values: the major and the minor version. Since,
  -      by definition, there are no API changes across patch versions,
  -      that symbol can be safely ignored. Note that any kind of a check
  -      for a minimum version will then pin that application to at least
  -      that version. The application's installation mechanism should
  -      then ensure that that minimal version has been installed (for
  -      example, using RPM dependency checks).
  -    </p>
  -    <p>
  -      If the feature changes across minor versions are source
  -      compatible, but are (say) simply different choices of values to
  -      pass into the library, then an application can support a wider
  -      variety of installed libraries if it avoids compile-time checks.
  -    </p>
  -    
  -    <h3>Run-time Checks</h3>
  -    <p>
  -      A library meeting this specification should support a way for an
  -      application to determine the library's version at
  -      <em>run-time</em>. This will usually be emboded as a simple
  -      function which returns the <tt>MAJOR</tt>, <tt>MINOR</tt>, and
  -      <tt>PATCH</tt> triplet in some form.
  -    </p>
  -    <p>
  -      Run-time checks are preferable in all cases. This type of check
  -      enables an application to run against a wider variety of minor
  -      releases of a library (the application is "<em>less
  -      coupled</em>" to a particular library release). Of course, if an
  -      application requires a function that was introduced in a later,
  -      minor release, then the application will require that, at least,
  -      that release is installed on the target system.
  -    </p>
  -    <p>
  -      Run-time checks are particurly important if the application is
  -      trying to determine if the library has a particular bug that may
  -      need to be worked around, but has been fixed in a later
  -      release. If the bug is fixed in a patch release, then the only
  -      avenue for an application is to perform a runtime check. This is
  -      because an application cannot require a specific patch level of
  -      the library to be installed -- those libraries are perfectly
  -      forward and backwards compatible, and the administrator is free
  -      to choose any patch release, knowing that all applications will
  -      continue to function properly. If the bug was fixed in a minor
  -      release, then it is possible to use a compile-time check, but
  -      that would create a tighter coupling to the library.
  -    </p>
  -
  -    <h2><a name="parallel">Parallel Installation</a></h2>
  -    <p>
  -      <em>Parallel installation</em> refers to the ability to install
  -      multiple versions of a library simultaneously -- they exist in
  -      parallel. This document will not discuss the full rationale for
  -      why this is important, but will instead detail how this
  -      versioning specification maps onto those concepts. Please refer
  -      to
  -      <a href="http://www106.pair.com/rhp/parallel.html">Havoc
  -        Pennington's document</a> for futher details and the rationale
  -      behind this form of parallel installation.
  -    </p>
  -
  -    <h3>Library Naming</h3>
  -    <p>
  -      On Unix-ish platforms, the library name should include the
  -      <tt>MAJOR</tt> version number:
  -    </p>
  -    <blockquote>
  -      <tt>libFOO-MAJOR.so</tt>
  -    </blockquote>
  -    <p>
  -      This strategy allows an application to explicitly state which
  -      version of the library that it wants to link against. If the
  -      application was built for version 2 of the API, then it can link
  -      against <tt>libFOO-2.so</tt>. If another application was built
  -      against version 3 of the API, then it links against
  -      <tt>libFOO-3.so</tt>. Since both libraries can reside on the
  -      system at the same time, both applications' needs can be
  -      satisfied.
  -    </p>
  -
  -    <p>
  -      Typically, shared libraries on Unix-ish platforms will set up
  -      symlinks from the <tt>.so</tt> library to specific versions of
  -      that library. For example:
  -    </p>
  -    <blockquote>
  -      <tt>
  -        libFOO-MAJOR.so -> libFOO-MAJOR.so.0
  -        <br>
  -        libFOO-MAJOR.so.0 -> libFOO-MAJOR.so.0.MINOR.PATCH
  -      </tt>
  -    </blockquote>
  -    <p>
  -      In this configuration, applications will be bound to the
  -      <tt>.so.0</tt> library. The minor version does not come into
  -      play here because we want applications to dynamically load and
  -      link to the new library when a new minor version is
  -      installed. Thus, the <tt>MINOR</tt> and the <tt>PATCH</tt>
  -      values are relegated to the library name after the
  -      <tt>.so.0</tt> portion.
  -    </p>
  -    <p>
  -      The implication here is that build systems for libraries should
  -      arrange to generate <tt>.so</tt> libraries matching the above
  -      pattern.
  -    </p>
  -    
  -    <h3>Include Directories</h3>
  -    <p>
  -      The default installation directory for a library's include files
  -      should specify the <tt>MAJOR</tt> version number, and should
  -      normally be installed as a subdirectory in some standard
  -      location. For example:
  -    </p>
  -    <blockquote>
  -      <!-- stupid xemacs mode getting confused by forward slashes... -->
  -      <tt>&#2f;usr&#2f;include&#2f;FOO-MAJOR&#2f;</tt>
  -    </blockquote>
  -    <p>
  -      An application can place the <tt>FOO-MAJOR</tt> directory on its
  -      include path and include the files normally:
  -    </p>
  -    <blockquote>
  -      <tt>
  -        #include &lt;FOO-stuff.h&gt;
  -        <br>
  -        #include &lt;FOO-more.h&gt;
  -      </tt>
  -    </blockquote>
  -    <p>
  -      Depending upon the API that the application is designed to work
  -      against, it can simply include different versions of the include
  -      directory.
  -    </p>
  -
  -    <h3>Other Files</h3>
  -    <p>
  -      <strong>NOTE:</strong>
  -      There is no recommendation at this time for the best and
  -      proper handling of, say, <tt>FOO-config</tt> types of files. Or
  -      non-code types of files (e.g. things that typically get
  -      installed into areas like <tt>&#2f;usr&#2f;shared</tt>).
  -    </p>
  -    <p>
  -      Further thought and exploration is needed here.
  -    </p>
  -
  -    <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>
  -
  -    <hr />
  -Last modified: $Date$
  -  </body>
  +      <dt>Deprecating functions</dt>
  +      <dd>Since a function must remain available for applications coded
  +          against a previous minor release, it is only possible to
  +          "<em>deprecate</em>" a function. It <strong>cannot</strong> 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).
  +
  +          <p>If you deprecate a function in APR, please mark it as such in the
  +          function documentation, using the doxygen "<code>\deprecated</code>"
  +          tag.  Deprecated functions can only be removed in major releases.</p>
  +
  +          <p>A deprecated function should remain available <em>through</em>
  +          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.</p>
  +
  +          <p>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.</p>
  +
  +          <p>Note that all deprecated functions will be removed at the next 
  +          major version bump.</p>
  +
  +      </dd></dl>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Major Versions</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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 (deprecated) functions</li>
  +  <li>fold together macro-ized function replacements</li>
  +</ul>
  +  </blockquote>
  + </td></tr>
  +</table>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="vsncheck"><strong>Version Checking</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>In many cases, the user of a library will need to check the version that
  +they are compiling against, or that is being used at runtime. Because of the
  +strict rules of source and binary compatibility, these checks can be simpler
  +and more complicated depending on what is needed.</p>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Compile-time Checks</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>Libraries should make their version number available as compile-time
  +constants. For example:</p>
  +<blockquote>
  +  <tt>
  +    #define FOO_MAJOR_VERSION 1
  +    <br />
  +    #define FOO_MINOR_VERSION 4
  +    <br />
  +    #define FOO_PATCH_VERSION 0
  +  </tt>
  +</blockquote>
  +<p>The above symbols are the minimum required for this specification.</p>
  +<p>An application that desires, at compile-time, to decide on whether and how
  +to use a particular library feature needs to only check two values: the major
  +and the minor version. Since, by definition, there are no API changes across
  +patch versions, that symbol can be safely ignored. Note that any kind of a
  +check for a minimum version will then pin that application to at least that
  +version. The application's installation mechanism should then ensure that that
  +minimal version has been installed (for example, using RPM dependency checks).
  +</p>
  +<p>If the feature changes across minor versions are source compatible, but
  +are (say) simply different choices of values to pass into the library, then an
  +application can support a wider variety of installed libraries if it avoids
  +compile-time checks.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Run-time Checks</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>A library meeting this specification should support a way for an
  +application to determine the library's version at <em>run-time</em>. This will
  +usually be emboded as a simple function which returns the <tt>MAJOR</tt>,
  +<tt>MINOR</tt>, and <tt>PATCH</tt> triplet in some form.</p>
  +<p>Run-time checks are preferable in all cases. This type of check enables an
  +application to run against a wider variety of minor releases of a library (the
  +application is "<em>less coupled</em>" to a particular library release). Of
  +course, if an application requires a function that was introduced in a later,
  +minor release, then the application will require that, at least, that release
  +is installed on the target system.</p>
  +<p>Run-time checks are particurly important if the application is trying to
  +determine if the library has a particular bug that may need to be worked
  +around, but has been fixed in a later release. If the bug is fixed in a patch
  +release, then the only avenue for an application is to perform a runtime check.
  +This is because an application cannot require a specific patch level of the
  +library to be installed -- those libraries are perfectly forward and backwards
  +compatible, and the administrator is free to choose any patch release, knowing
  +that all applications will continue to function properly. If the bug was fixed
  +in a minor release, then it is possible to use a compile-time check, but that
  +would create a tighter coupling to the library. </p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="parallel"><strong>Parallel Installation</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p><em>Parallel installation</em> refers to the ability to install multiple
  +versions of a library simultaneously -- they exist in parallel. This document
  +will not discuss the full rationale for why this is important, but will instead
  +detail how this versioning specification maps onto those concepts. Please refer
  +to <a href="http://www106.pair.com/rhp/parallel.html">Havoc Pennington's
  +document</a> for futher details and the rationale behind this form of parallel
  +installation.</p>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Library Naming</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>On Unix-ish platforms, the library name should include the <tt>MAJOR</tt>
  +version number: </p>
  +<blockquote><tt>libFOO-MAJOR.so</tt></blockquote>
  +<p>This strategy allows an application to explicitly state which version
  +of the library that it wants to link against. If the application was built for
  +version 2 of the API, then it can link against <tt>libFOO-2.so</tt>. If another
  +application was built against version 3 of the API, then it links against
  +<tt>libFOO-3.so</tt>. Since both libraries can reside on the system at the same
  +time, both applications' needs can be satisfied.</p>
  +<p>Typically, shared libraries on Unix-ish platforms will set up symlinks from
  +the <tt>.so</tt> library to specific versions of that library. For example:
  +</p>
  +<blockquote>
  +  <tt>libFOO-MAJOR.so -&gt; libFOO-MAJOR.so.0<br />
  +      libFOO-MAJOR.so.0 -&gt; libFOO-MAJOR.so.0.MINOR.PATCH</tt>
  +</blockquote>
  +<p>In this configuration, applications will be bound to the <tt>.so.0</tt>
  +library. The minor version does not come into play here because we want
  +applications to dynamically load and link to the new library when a new minor
  +version is installed. Thus, the <tt>MINOR</tt> and the <tt>PATCH</tt> values
  +are relegated to the library name after the <tt>.so.0</tt> portion.</p>
  +<p>The implication here is that build systems for libraries should arrange
  +to generate <tt>.so</tt> libraries matching the above pattern.  </p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Include Directories</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>The default installation directory for a library's include files should
  +specify the <tt>MAJOR</tt> version number, and should normally be installed as
  +a subdirectory in some standard location. For example:</p>
  +<blockquote>
  +  <!-- stupid xemacs mode getting confused by forward slashes... -->
  +  <tt>/usr/include/FOO-MAJOR/</tt>
  +</blockquote>
  +<p>An application can place the <tt>FOO-MAJOR</tt> directory on its
  +include path and include the files normally:</p>
  +<blockquote>
  +  <tt>#include &lt;FOO-stuff.h&gt;<br />
  +      #include &lt;FOO-more.h&gt;</tt>
  +</blockquote>
  +<p>Depending upon the API that the application is designed to work against, it
  +can simply include different versions of the include directory.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +<table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#828DA6">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Other Files</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p><strong>NOTE:</strong> There is no recommendation at this time for the
  +best and proper handling of, say, <tt>FOO-config</tt> types of files. Or
  +non-code types of files (e.g. things that typically get installed into areas
  +like <tt>/usr/shared</tt>).</p>
  +<p>Further thought and exploration is needed here.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <a name="notes"><strong>Other Notes</strong></a>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<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>
  +  </blockquote>
  + </td></tr>
  +</table>
  +         </td>
  +   </tr>
  +   <!-- FOOTER -->
  +   <tr><td colspan="2"><hr noshade="noshade" size="1"/></td></tr>
  +   <tr><td colspan="2" align="center">
  +        <font size="-1">
  +         <em>Copyright &#169; 1999-2003, The Apache Software Foundation</em>
  +        </font>
  +       </td>
  +   </tr>
  +  </table>
  + </body>
   </html>
  
  
  
  1.1                  apr-site/xdocs/guidelines.xml
  
  Index: guidelines.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
    <properties>
      <author email="dev@apr.apache.org">APR Developers</author>
      <title>Project Guidelines</title>
    </properties>
  <body>
  
  <section>
  <title>APR Project Guidelines</title>
  
  <p>This page describes the procedures and guidelines used by the APR
  Project.</p>
  
  <p><i>this is an initial draft</i></p>
  </section>
  
  <section>
  <title>Commit Access</title>
  
  <p>Commit access will be somewhere between the "lengthy" process of httpd,
  and the more "open" process in Subversion.</p>
  
  <p>Specifically, if a person submits several reasonable patches that apply
  well and follow the general guidelines, and that person appears to "get the
  process", then they will be provided commit access.</p>
  
  <p>This policy generally depends upon the fact that we can always recover
  from problematic committers (since we use source control). The PMC also
  reserves the right to suspend commit privileges, if other APR members end up
  spending too much time dealing with problematic commits.</p>
  </section>
  
  <section>
  <title>Change Process</title>
  
  <p>Most changes (bug fixes and minor, commonsense feature adds) do not
  require review.  Developers are encouraged to request review for:</p>
  
  <ul>
    <li>Large changes affecting many files</li>
    <li>Changes to interfaces</li>
    <li>Changes that commit APR to one option out of an exclusive set</li>
    <li>Any change the developer wants a second (or Nth) opinion on</li>
  </ul>
  
  <p>Anyone may retroactively cause someone's change to be reviewed by
  requesting review after it was committed, and at their discretion may
  revert the change until it is approved.</p>
  
  <p>The above process is called "Commit Then Review" (or CTR). As of
  this time, the group does not see a need to ever use a "Review
  Then Commit" (RTC) process.</p>
  
  </section>
  
  <section>
  <title>PMC Membership</title>
  
  <p>PMC membership is attained through a "consensus approval" process
  according to the <a href="http://httpd.apache.org/dev/guidelines.html"
  >standard ASF guidelines</a> (as set out by HTTP Server).  The voters are the
  existing PMC members.</p>
  
  <p>The general policy is to accept committers who have demonstrated
  longevity in dev/doc/admin ability and interest in the APR project.</p>
  
  </section>
  
  <section>
  <title>Decision Making: Consensus and Voting</title>
  
      <dl>
        <dt><strong>NOTE:</strong></dt>
        <dd>
    The following text describes the precise rules and procedure
    for voting and decision making. In general, the behavior
    embodied in these rules is part of the "gestalt" of the group,
    and the formal use of these processes is not required.
        </dd>
      </dl>
  
  <p>Whenever possible, decisions are made by consensus.  Consensus is reached
  when both the following conditions are met: a committer indicates that
  consensus has been reached, and no committer claims that consensus has not yet
  been reached.  On any given issue, there is a 72-hour window after a claim of
  consensus before the consensus is considered binding, to give people time to
  react.</p>
  
  
  <p>
  [ gjs: changes can always be reverted, so why a window?
    and why is a decision ever "binding"? ]
  <br />
  [ gjs: need some text that describes the use of +/- 0/1 for
    talking about changes and their use in deciding whether
    consensus has been reached ]
  </p>
  
  <p>For decisions on which consensus is not reachable or is not attempted,
  the group votes, using approval voting:</p>
  
  <blockquote>
  
  <p>Each voter is allowed to cast a single vote for each of as many of the
  ballot choices as desired -- that is, the voter votes for all choices of which
  the voter "approves."  Each vote is one of: </p>
  
  <ul>
    <li>+1 : Yes, agree that the choice should be performed.</li>
    <li>+0 : Seems fine, but I can live without it</li>
    <li>-0 : Doesn't seem right, but I won't argue against it</li>
    <li>-1 : No, I am against this choice being performed.</li>
  </ul>
  
  </blockquote>
  
  <p>Choices receiving positive totals may be performed.</p>
  
  <p>When the set of ballot choices cannot be agreed on, the PMC chair decides
  the set.  If the question of whether consensus has been reached or not is
  undecidable (this "can't happen", but who knows), the chair decides whether or
  not it has been reached.</p>
  
  <p>Changes to these decision-making procedures may be made by consensus.  But,
  if such a change does reach the voting stage, then positive votes must
  outnumber negative votes by a two-to-one ratio, or greater, for the change to
  take effect.</p>
  
  <section>
  <title>Veto as a vote</title>
  
  <p>A voter explicitly stating that they veto the decision, providing a
  justification of their veto is sufficient to table a vote until the issue is
  addressed and the vetoer or those who agreed concur that the the issue is
  addressed.</p>
  </section>
  
  <section>
  <title>Voting Procedure Technicalities</title>
  
  <p>Votes are tallied in the <tt>STATUS</tt> file, adjacent to the action item
  under vote.  All votes must be either sent to the mailing list or added
  directly to the <tt>STATUS</tt> file entry for that action item.</p>
  
  </section>
  </section>
  
  </body>
  </document>
  
  
  
  
  1.1                  apr-site/xdocs/versioning.xml
  
  Index: versioning.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
    <properties>
      <author email="dev@apr.apache.org">APR Developers</author>
      <title>Versioning Numbering Concepts</title>
    </properties>
  <body>
  
  <section>
  <title>APR's Version Numbering</title>
  
  <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="#strategy">Strategy</a></li>
    <li><a href="#vsncheck">Version Checking</a></li>
    <li><a href="#parallel">Parallel Installation</a></li>
    <li><a href="#notes">Other Notes</a></li>
  </ul>
  
  </section>
  
  <section id="basics">
  <title>The Basics</title>
  
  <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>
  
  <p> It is important to note that a library that has not reached 1.0.0 is
  <strong>not</strong> subject to the guidelines described in this document.
  Before a 1.0 release (version 0.x.y), the API <em>can</em> and <em>will</em> be
  changing freely, without regard to the restrictions detailed below.</p>
  
  </section>
  
  <section id="source">
  <title>Source Compatibility</title>
  
  <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 or operate
  against previous minor versions.</p>
  
  </section>
  
  <section id="binary">
  <title>Binary Compatibility</title>
  
  <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>
  
  </section>
  
  <section id="examples">
  <title>Examples</title>
  
  <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>
  
  </section>
  
  <section id="strategy">
  <title>Strategy</title>
  
  <p>This section details how we will build the code to meet the above
  requirements and guidelines.</p>
  
  <section>
  <title>Patch Version</title>
  
  <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>
  </section>
  
  <section>
  <title>Minor Versions</title>
  
  <p>Minor releases can introduce new functions, new symbolic and enumerated
  constants, and deprecate existing functions.</p>
  
      <dl>
        <dt>New functions</dt>
  
        <dd><p>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>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.</p>
  
            <p>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.</p>
          </dd>
  
        <dt>New constants</dt>
        <dd>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.</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. Further, if an application is
            <em>designed</em> 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.
  
            <p>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).</p>
  
            <p>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.</p>
  
            <p>Constants (enumerated values and preprocessor macros) are
            <strong>not</strong> 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.</p>
        </dd>
  
        <dt>Deprecating functions</dt>
        <dd>Since a function must remain available for applications coded
            against a previous minor release, it is only possible to
            "<em>deprecate</em>" a function. It <strong>cannot</strong> 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).
  
            <p>If you deprecate a function in APR, please mark it as such in the
            function documentation, using the doxygen "<code>\deprecated</code>"
            tag.  Deprecated functions can only be removed in major releases.</p>
  
            <p>A deprecated function should remain available <em>through</em>
            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.</p>
  
            <p>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.</p>
  
            <p>Note that all deprecated functions will be removed at the next 
            major version bump.</p>
  
        </dd></dl>
  
  </section>
  
  <section>
  <title>Major Versions</title>
  
  <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 (deprecated) functions</li>
    <li>fold together macro-ized function replacements</li>
  </ul>
  
  </section>
  </section>
  
  <section id="vsncheck">
  <title>Version Checking</title>
  
  <p>In many cases, the user of a library will need to check the version that
  they are compiling against, or that is being used at runtime. Because of the
  strict rules of source and binary compatibility, these checks can be simpler
  and more complicated depending on what is needed.</p>
  
  <section>
  <title>Compile-time Checks</title>
  
  <p>Libraries should make their version number available as compile-time
  constants. For example:</p>
  
  <blockquote>
    <tt>
      #define FOO_MAJOR_VERSION 1
      <br />
      #define FOO_MINOR_VERSION 4
      <br />
      #define FOO_PATCH_VERSION 0
    </tt>
  </blockquote>
  
  <p>The above symbols are the minimum required for this specification.</p>
  
  <p>An application that desires, at compile-time, to decide on whether and how
  to use a particular library feature needs to only check two values: the major
  and the minor version. Since, by definition, there are no API changes across
  patch versions, that symbol can be safely ignored. Note that any kind of a
  check for a minimum version will then pin that application to at least that
  version. The application's installation mechanism should then ensure that that
  minimal version has been installed (for example, using RPM dependency checks).
  </p>
  
  <p>If the feature changes across minor versions are source compatible, but
  are (say) simply different choices of values to pass into the library, then an
  application can support a wider variety of installed libraries if it avoids
  compile-time checks.</p>
  
  </section>
  
  <section>
  <title>Run-time Checks</title>
  
  <p>A library meeting this specification should support a way for an
  application to determine the library's version at <em>run-time</em>. This will
  usually be emboded as a simple function which returns the <tt>MAJOR</tt>,
  <tt>MINOR</tt>, and <tt>PATCH</tt> triplet in some form.</p>
  
  <p>Run-time checks are preferable in all cases. This type of check enables an
  application to run against a wider variety of minor releases of a library (the
  application is "<em>less coupled</em>" to a particular library release). Of
  course, if an application requires a function that was introduced in a later,
  minor release, then the application will require that, at least, that release
  is installed on the target system.</p>
  
  <p>Run-time checks are particurly important if the application is trying to
  determine if the library has a particular bug that may need to be worked
  around, but has been fixed in a later release. If the bug is fixed in a patch
  release, then the only avenue for an application is to perform a runtime check.
  This is because an application cannot require a specific patch level of the
  library to be installed -- those libraries are perfectly forward and backwards
  compatible, and the administrator is free to choose any patch release, knowing
  that all applications will continue to function properly. If the bug was fixed
  in a minor release, then it is possible to use a compile-time check, but that
  would create a tighter coupling to the library. </p>
  
  </section>
  
  </section>
  
  <section id="parallel">
  <title>Parallel Installation</title>
  
  <p><em>Parallel installation</em> refers to the ability to install multiple
  versions of a library simultaneously -- they exist in parallel. This document
  will not discuss the full rationale for why this is important, but will instead
  detail how this versioning specification maps onto those concepts. Please refer
  to <a href="http://www106.pair.com/rhp/parallel.html">Havoc Pennington's
  document</a> for futher details and the rationale behind this form of parallel
  installation.</p>
  
  <section>
  <title>Library Naming</title>
  
  <p>On Unix-ish platforms, the library name should include the <tt>MAJOR</tt>
  version number: </p>
  
  <blockquote><tt>libFOO-MAJOR.so</tt></blockquote>
  
  <p>This strategy allows an application to explicitly state which version
  of the library that it wants to link against. If the application was built for
  version 2 of the API, then it can link against <tt>libFOO-2.so</tt>. If another
  application was built against version 3 of the API, then it links against
  <tt>libFOO-3.so</tt>. Since both libraries can reside on the system at the same
  time, both applications' needs can be satisfied.</p>
  
  <p>Typically, shared libraries on Unix-ish platforms will set up symlinks from
  the <tt>.so</tt> library to specific versions of that library. For example:
  </p>
  
  <blockquote>
    <tt>libFOO-MAJOR.so -> libFOO-MAJOR.so.0<br />
        libFOO-MAJOR.so.0 -> libFOO-MAJOR.so.0.MINOR.PATCH</tt>
  </blockquote>
  
  <p>In this configuration, applications will be bound to the <tt>.so.0</tt>
  library. The minor version does not come into play here because we want
  applications to dynamically load and link to the new library when a new minor
  version is installed. Thus, the <tt>MINOR</tt> and the <tt>PATCH</tt> values
  are relegated to the library name after the <tt>.so.0</tt> portion.</p>
  
  <p>The implication here is that build systems for libraries should arrange
  to generate <tt>.so</tt> libraries matching the above pattern.  </p>
  
  </section>
  
  <section>
  <title>Include Directories</title>
  
  <p>The default installation directory for a library's include files should
  specify the <tt>MAJOR</tt> version number, and should normally be installed as
  a subdirectory in some standard location. For example:</p>
  
  <blockquote>
    <!-- stupid xemacs mode getting confused by forward slashes... -->
    <tt>&#47;usr&#47;include&#47;FOO-MAJOR&#47;</tt>
  </blockquote>
  
  <p>An application can place the <tt>FOO-MAJOR</tt> directory on its
  include path and include the files normally:</p>
  
  <blockquote>
    <tt>#include &lt;FOO-stuff.h&gt;<br />
        #include &lt;FOO-more.h&gt;</tt>
  </blockquote>
  
  <p>Depending upon the API that the application is designed to work against, it
  can simply include different versions of the include directory.</p>
  
  </section>
  
  <section>
  <title>Other Files</title>
  
  <p><strong>NOTE:</strong> There is no recommendation at this time for the
  best and proper handling of, say, <tt>FOO-config</tt> types of files. Or
  non-code types of files (e.g. things that typically get installed into areas
  like <tt>&#47;usr&#47;shared</tt>).</p>
  
  <p>Further thought and exploration is needed here.</p>
  
  </section>
  </section>
  
  <section id="notes">
  <title>Other Notes</title>
  
  <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>
  
  </section>
  </body>
  </document>
  
  
  
  

Mime
View raw message