apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg Stein <gst...@lyra.org>
Subject Re: apr versioning
Date Mon, 12 Nov 2001 00:56:41 GMT
On Sun, Nov 11, 2001 at 03:54:37PM -0800, Ryan Bloom wrote:
> On Sunday 11 November 2001 02:07 pm, Greg Stein wrote:
>...
> > 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.
> 
> In general, I like the approach.  I am on the fence about the is_dev stuff,
> but I need to think about it more.  I'm just not sure we need it, but then I
> think about it, and I think it's a nice feature.  I can go either way on that I
> guess.

For httpd, we have the -dev thing, and it seems to work really well. People
can say they are testing against 2.0.29-dev, and we know that means from CVS
at some point. And more specifically, it means they aren't using a "proper"
release.

I use the same -dev technique in ViewCVS and edna, and found it works great.

So... the question was then how to add that to APR(UTIL) in an easy-to-use
fashion. We needed something testable by the preprocessor to create "-dev"
for the version string, so that meant either a simple defined / not-defined
test, or a number. I decided on #ifdef as that seemed more "boolean" than
using a number.

>...
> > > 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.
> 
> It does.  :-)  Wow Greg, what happened.  All we used to do was fight.  Now
> we agree more often than not.  :-)

hehe... I'll strive to fix that in the future. :-)

[ actually, I think it is just related to taking more time to fully explain
  things rather than saying "that isn't right." ]

> I don't believe that backwards compat is necessary at all, given the definitions
> above.

Excellent. I was a bit worried for a second :-)

> > > 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?
> 
> I agree in part only.  The only reason that an app would need source changes are if
> APIs have been removed or the prototype was changed.  We shouldn't do that.
> If we want to remove an API, then we should mark it deprecated for a release,
> and then remove it in the next major bump.  That would basically state that 
> an app would have until the next release to modify their code, or they will
> be stuck on an older version of APR.  
> 
> If we are modifying an API, then we should continue to support the old API,
> although it should be marked as deprecated.
> 
> Each release should come with a list of deprecated APIs if any exist, so that
> our users can easily determine the problem functions.
> 
> What I don't want to see, is I wrote a program against APR 1.0.99, and then
> 2.0 is released.  My program all of a sudden does not compile anymore,
> because an API was removed without warning.  I would rather see the API
> moved to a new file, deprecated2.0.c, and in APR 3.0, that file should be
> removed, removing the deprecated functions.
> 
> This provides a lot of warning before a function disappears.  Does that make
> sense?

<agreement-alert/>

It does make sense. A difference in the MAJOR version is a technical thing
only: source code changes may need to be made. *Policy* says *when* apps
must do source changes. I was speaking more abstractly with "1.x is not
source compatible with 2.x", when I was intending "... with later than 1.x".

So yes: the policy of "1.x is source compat with 2.x, but 1.x may /not/ be
source compatible with 3.x" seems like an okay policy.

One fallout from it, though, is that "apr_file_open()" is the best name for
that function. If we can't modify its name/prototype in until 3.0, then a
2.0 could end up with "apr_file_open2()" or something. The users would
switch over to open2(), and then we'd fix open() in 3.0 (leaving open2 until
its removal in 4.0). So the user would change their code *again* when 3.0
comes out.

If we simply allow a change in a major version, then the user only needs to
make one change.

Note that MINOR changes can introduce an API and deprecate another
(deprecate only! it would still exist). We could introduce open2() in 1.1
and deprecate the 1.0 open() call. In APR 2.0, we change open() and remove
open2().

Personally, I would keep source compatibility to MINOR versions only. We can
do a lot of changes there. At some point, we will find there is a lot of
crud, with this2() and that2() and over_there3(). Then we bump up to 2.0 and
clean up the API. Note that it would be a pretty mechanical translation from
1.x to 2.0, and a compat.h could be supplied to map this2() to this().
Meaning the original this() disappears or has a new prototype. Further, a
large change in overall model could end up being impossible if we have to
support the N-1 API in an N release. (e.g. the pipe example or changing how
the memory systems work).

So I'd say that we agree again, if you apply your policy to 1.x instead. It
can even be firmed up: we never remove an API in 1.x (although we can
deprecate them). They get deleted/changed in a major release.

[ you may have said that, but you said "until the next release"; we're
  saying the same thing if you meant "until the next major-bump release" ]


At this point, I think Ryan and I agree on the versioning mechanics
(with some possible discussion around -dev). I think we are close enough on
policy, too.

What do *others* think?

Cheers,
-g

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

Mime
View raw message