apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg Stein <gst...@lyra.org>
Subject apr versioning (was: cvs commit: ...)
Date Sun, 11 Nov 2001 22:07:28 GMT
On Sun, Nov 11, 2001 at 09:14:42AM -0800, Ryan Bloom wrote:
> On Saturday 10 November 2001 11:23 pm, gstein@apache.org wrote:
> 
> >     ### we have not defined source/binary compatibility guidelines yet and
> >     ### how those map against these (release) version numbers. a strawman
> >     ### would be the following text:
> 
> We should have this discussion now.

That is why the comment was there :-)

Also, I'd like feedback on the overall approach. If people don't have any
major issues with it, then I'll use the same thing in APRUTIL.

Also, if it seems fine, then I'll have configure.in extract the version
number from the header and pass it to libtool (to create libapr.so.X.Y.Z). I
just didn't want to do that work (a good bit of testing is involved) unless
people are happy with the overall approach.

> >     APR is binary-compatible (an app compiled against one version does not
> >     need to be recompiled to work against another version) for the same
> >     MAJOR and MINOR versions.
> >
> >     APR is source-compatible (an app needs to be recompiled, but will work
> >     the same) for the same MAJOR version.
> >
> >     If the MAJOR version changes, then an application may need source
> > changes.
> 
> This is a library, backwards compatibility is a must.

Before using the term "backward compatible", we should define what we mean.
There are a couple different interpretations. (which is why I avoided it
above, altho I removed too much of my forward/backward discussion; the
comments need more tweaking)

APR needs to be "forward compatible". An app built against 1.0.0 should work
against later/future/forward releases of APR.

APR does not need to be "backward compatible". An app built against 1.3.2
does not have to work against previous releases of APR.

[ i.e. APR is moving backwards/forwards; what happens to the app? ]


The next question is what kinds of changes the app may need to make when the
version numbers change. Consider an app that was coded and compiled against
1.0.0. When a later version comes out, what happens?

1.0.0 -> 1.0.1 : no recompile; relink against new .a; new .so just works
1.0.0 -> 1.1.x : recompile. relink against .a and .so.
1.0.0 -> 2.x.y : source changes

Now consider an app built against <some> release; what is possible?

1.0.1 -> 1.0.0 : no recompile; relink against old .a; old .so just works
1.1.x -> 1.0.0 : won't work; the app may have used new 1.1 APIs
2.x.y -> 1.0.0 : won't work; needs source changes

> If we break backwards
> compat after we release, we will have broken a lot of users.  -0.9 for ever
> allowing backwards compat to be broken.

I agree, if your meaning of "backwards compat" actually matches my "forward
compat" definition above.

> If the MAJOR number is increasing,
> then a program should never need to be re-compiled, let alone source changes.

Going from APR 1.0 to APR 2.0 could definitely require source changes (and
those required changes is most likely *why* MAJOR was bumped). Are you
saying that an app built for 1.0.0 will never, ever need source changes?
That just isn't right, and it isn't feasible. Did I misunderstand what you
meant?


Here are the types of changes possible:

MAJOR version changes: fundamental changes in usage of the API (e.g. using
    SMS rather than pools), or fundamental changes in the objects (e.g.
    pipes get their own object, rather than modelling as files).

MINOR version changes: adding new APIs, and using macros to remap old APIs
    into the new ones (thus keeping source compat for old API forms).

PATCH version changes: no substative changes to the headers (e.g. just
    changes in comments). Bug fixes only to the code.


This follows a pattern used by most projects that I can think of.

Apps want to link against libapr-X.Y.so to ensure they get the right one
(this is similar to Berkeley DB publishing libdb-3.2 vs libdb-3.3). Apps
won't have to care about the patch version. RPM-style dependencies are
always based on MAJOR.MINOR. The patch usually isn't required in there,
although an RPM can certainly do that to ensure that a certain bug has been
fixed, which it might otherwise run into.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/

Mime
View raw message