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
Date Tue, 13 Aug 2002 17:42:06 GMT
gstein      2002/08/13 10:42:06

  Modified:    .        versioning.html
  Log:
  Functions actually *cannot* be replace via macros, so note this and
  the reasons why. Clarify that pre-1.0 releases are not subject to
  these rules by moving that text out of the "Other Notes" area. Do a
  bunch of wording tweaks and add some more clarification to areas of
  this document.
  
  Revision  Changes    Path
  1.5       +59 -66    apr-site/versioning.html
  
  Index: versioning.html
  ===================================================================
  RCS file: /home/cvs/apr-site/versioning.html,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- versioning.html	10 May 2002 22:26:02 -0000	1.4
  +++ versioning.html	13 Aug 2002 17:42:06 -0000	1.5
  @@ -39,6 +39,13 @@
         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>
  @@ -51,7 +58,7 @@
         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.
  +      longer build or operate against previous minor versions.
       </p>
   
       <h2><a name="binary">Binary Compatibility</a></h2>
  @@ -166,8 +173,7 @@
       <h3>Minor Versions</h3>
       <p>
         Minor releases can introduce new functions, new symbolic and
  -      enumerated constants, and (with restrictions) replace existing
  -      functions.
  +      enumerated constants, and deprecate existing functions.
       </p>
       <dl>
         <dt>New functions</dt>
  @@ -193,52 +199,33 @@
   	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:
  +	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>
  -	<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
  +	  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.
  @@ -247,18 +234,26 @@
         
         <dt>Deprecating functions</dt>
         <dd>
  -        <p>
  -	  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>
  -	<p>
  -	  If you deprecate a function in APR, please mark it as such in
  -	  the function documentation, using the doxygen "\deprecated" tag.
  -	  Deprecated functions can only be removed in major releases.
  +	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
  @@ -266,6 +261,10 @@
   	  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>
  @@ -291,12 +290,6 @@
       <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 />
   Last modified: $Date$
  
  
  

Mime
View raw message