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