You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by gs...@apache.org on 2002/08/13 19:42:06 UTC
cvs commit: apr-site versioning.html
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$
RE: cvs commit: apr-site versioning.html
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
At 08:47 AM 8/14/2002, Bill Stoddard wrote:
> > And that 0.9.0 is going to be whatever is in APR today. If somebody wants
> > their darned pet feature in 1.0, then they can get it code before
> > that date.
> > But I want something *versioned* *today*. SVN users are dyin' cuz we can't
> > point people at a specific APR release. The best we can do is "use CVS
> > HEAD", which (of course) sucks ass. After a release, at least we can say
> > "use at least 0.9.0".
> >
> > Cheers,
> > -g
> >
>
>+1
I'll see your +1 and raise you a ++1.
Today should be 0.9.0. Flesh it out and get to 1.0.0 ... and let builders
start implementing the versioning checks as of -now-.
Bill
Re: cvs commit: apr-site versioning.html
Posted by Branko Čibej <br...@xbc.nu>.
Greg Stein wrote:
>And that 0.9.0 is going to be whatever is in APR today. If somebody wants
>their darned pet feature in 1.0, then they can get it code before that date.
>But I want something *versioned* *today*. SVN users are dyin' cuz we can't
>point people at a specific APR release. The best we can do is "use CVS
>HEAD", which (of course) sucks ass. After a release, at least we can say
>"use at least 0.9.0".
>
>
+1. Let's see if we can get APR to 1.0 before Subversion hits Beta. :-)
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
Re: cvs commit: apr-site versioning.html
Posted by Aaron Bannert <aa...@clove.org>.
> > > And that 0.9.0 is going to be whatever is in APR today. If somebody wants
> > > their darned pet feature in 1.0, then they can get it code before
> > > that date.
> > > But I want something *versioned* *today*. SVN users are dyin' cuz we can't
> > > point people at a specific APR release. The best we can do is "use CVS
> > > HEAD", which (of course) sucks ass. After a release, at least we can say
> > > "use at least 0.9.0".
I want a release as well, +1
-aaron
RE: cvs commit: apr-site versioning.html
Posted by Bill Stoddard <bi...@wstoddard.com>.
> And that 0.9.0 is going to be whatever is in APR today. If somebody wants
> their darned pet feature in 1.0, then they can get it code before
> that date.
> But I want something *versioned* *today*. SVN users are dyin' cuz we can't
> point people at a specific APR release. The best we can do is "use CVS
> HEAD", which (of course) sucks ass. After a release, at least we can say
> "use at least 0.9.0".
>
> Cheers,
> -g
>
+1
Re: cvs commit: apr-site versioning.html
Posted by Greg Stein <gs...@lyra.org>.
On Tue, Aug 13, 2002 at 11:05:29AM -0700, Aaron Bannert wrote:
> On Tue, Aug 13, 2002 at 05:42:06PM -0000, gstein@apache.org wrote:
> > 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.
>
> This is a completely agreeable theory in an ideal world where our library
> project is just beginning. The problem is we already have a near-complete
> library, and even though we don't call it 1.0, many projects use and
> *depend* on it. IMHO we should have reached 1.0 a long time ago, and
> the fact that we have so many projects using it proves that.
For the APR situation... sure. But the doc is also designed for other
projects to use/refer to. In particular, Neon and SVN are "pre 1.0" and are
changing their interfaces. The 0.x.y rule is their magic bullet for escaping
the rules until they decide to do a formal release.
> I move that we implement a runtime version checking scheme in APR and
> then release 1.0 as soon as possible, at the same time adopting the
> above versioning definitions.
Sure, that's fine. But I'm going to be doing a 0.9.0 as soon as I can. I
want to update some of the bits for versioning the resulting .so file, and
then I'm going to package up a release.
And that 0.9.0 is going to be whatever is in APR today. If somebody wants
their darned pet feature in 1.0, then they can get it code before that date.
But I want something *versioned* *today*. SVN users are dyin' cuz we can't
point people at a specific APR release. The best we can do is "use CVS
HEAD", which (of course) sucks ass. After a release, at least we can say
"use at least 0.9.0".
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
Re: cvs commit: apr-site versioning.html
Posted by Aaron Bannert <aa...@clove.org>.
On Tue, Aug 13, 2002 at 05:42:06PM -0000, gstein@apache.org wrote:
> 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.
This is a completely agreeable theory in an ideal world where our library
project is just beginning. The problem is we already have a near-complete
library, and even though we don't call it 1.0, many projects use and
*depend* on it. IMHO we should have reached 1.0 a long time ago, and
the fact that we have so many projects using it proves that.
I move that we implement a runtime version checking scheme in APR and
then release 1.0 as soon as possible, at the same time adopting the
above versioning definitions.
-aaron