You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by kf...@collab.net on 2004/01/08 22:24:56 UTC
Re: API-changing releases was Re: concerns about issue #1682
Justin Erenkrantz <ju...@erenkrantz.com> writes:
> > If you believe (as I do) that we are *bound* to discover more API
> > issues after we release 1.0 anyway, and that they will necessitate an
> > API-changing release sooner rather than later anyway, then this patch
> > should be left out of 1.0.
>
> Once we hit 1.0, you can't change any existing API prototypes until 2.0.
>
> So, say, if we change our parameters to svn_client_blame, we have to
> have the old version as svn_client_blame and the new entry point as
> svn_client_blame2 (or something like that to make the names different).
Yah.
We could anticipatorily rename svn_client_blame right now, to
svn_client_simple_blame() or whatever, if we really felt strongly
about this. But I also think 2.0 is not too long to wait for such a
change -- it doesn't have to be infinitely far in the future, if we
feel there's a lot to change.
> Just want to make sure we're all on the same page here... -- justin
Yes. I was just over at http://apr.apache.org/versioning.html
checking on this.
Am I the only one who is beginning to feel that the requirements at
http://apr.apache.org/versioning.html are maybe a bit too strict? I
feel like I want to move everything down one notch: major version
number change means major new features; minor version means same basic
features, but possible API changes; patch level means bug fixes and
small stuff.
I'd like to be able to release something soon (like, six months) after
1.0, that fixes API problems which were only discovered by virtue of
1.0 being out in the world. Would be nice to call that new thing
"1.1" or "1.2", whereas "2.0" would imply huge new features (which
wouldn't be the case).
There's no reason why we can't discuss this while 1.0 stabilizes...
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by John Peacock <jp...@rowman.com>.
kfogel@collab.net wrote:
>>>http://apr.apache.org/versioning.html are maybe a bit too strict?
Those rules are actually for a very different beast: APR is a collection of
_library_ routines, not an application. Libraries are, by their very nature, a
slow moving target. So trying to force one versioning model on a very different
type of program is likely to cause some conceptional problems.
> The current release number system forces us to use major version
> increments for API changes. Unfortunately, the world at large assumes
> that a major version increment also means major new functionality. In
> other words, we have no way to introduce an API change without also
> either introducing major new features, or disappointing users who
> expect "more" from a 2.0.
Strongly agree.
>
> It seems to me like we have four concepts conflated in three numbers:
>
> a. Major feature additions
> b. API changes
> c. Changes that break binary compat
> d. Changes that maintain binary compat.
>
> Currently, (a) and (b) live in one number, the major version, and the
> others have their own numbers. My reshuffling gives (a) and (b) each
> their own number, and puts (c) and (d) in one number, the patch
> level.
I like this idea a lot, except that it limits conflates two contradictory
concepts into a single slot. I think it is also one reason why the even odd
model works better for this.
For "release" versions, the third tuple denotes binary compatible changes only.
For "developer" versions, the third tuple might include incompatible binary
changes (or it might not). The assumption is that between one "release" and
another (even number change), the API is bound to change at least somewhat.
The development stream proceeds pretty much at the pace that the current pre-1.0
stream has gone; the compatibility promise is only limited to 1 version (by
which we now refer to the third tuple). The release stream is always limited to
compatible changes.
John
--
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4720 Boston Way
Lanham, MD 20706
301-459-3366 x.5010
fax 301-429-5747
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Hudson <gh...@MIT.EDU>.
On Fri, 2004-01-09 at 15:59, kfogel@collab.net wrote:
> I'd like to know if other people agree we have a problem here,
> regardless of the eventual solution.
I have little doubt that you could guess my position here, but: nope.
If we are thinking about incompatibly changing the API without adding
major new features, we're probably making a big mistake. If we don't
consider API compatibility to be as important as every other facet of
Subversion, we may as well not have an API.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Stein <gs...@lyra.org>.
On Fri, Jan 09, 2004 at 03:06:43PM -0800, Justin Erenkrantz wrote:
> --On Friday, January 9, 2004 5:42 PM -0500 Greg Hudson <gh...@MIT.EDU>
> wrote:
>
> > (But, for reasons I've stated before, I really don't like that plan. We
> > should treat API compatibility as important enough that we don't break
> > it without raising the big red flag.)
>
> +1. -- justin
Amen, brothers. +1
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
--On Friday, January 9, 2004 5:42 PM -0500 Greg Hudson <gh...@MIT.EDU>
wrote:
> (But, for reasons I've stated before, I really don't like that plan. We
> should treat API compatibility as important enough that we don't break
> it without raising the big red flag.)
+1. -- justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Hudson <gh...@MIT.EDU>.
On Fri, 2004-01-09 at 17:32, Greg Stein wrote:
> 1.1.0.0
> 1.1.1.3
> 1.1.4.1
> 1.2.0.3
> 1.2.1.1
> 2.3.0.4
> 2.3.1.0
>
> Note that the second part is monotonically increasing, as that would be
> the major API version.
Not necessarily. We could have libsvn_subr-1.2.so.0.1.1, followed by
libsvn_subr-2.0.so.0.0.4.
(But, for reasons I've stated before, I really don't like that plan. We
should treat API compatibility as important enough that we don't break
it without raising the big red flag.)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Stein <gs...@lyra.org>.
On Fri, Jan 09, 2004 at 02:59:27PM -0600, kfogel@collab.net wrote:
>...
> I do think we have a real problem here. We can't change APIs without
> calling it 2.0, yet we've reason to believe we'll want to fix up some
> APIs *before* we have enough new features to justify calling it 2.0.
You can add functions until the cows come home. You just can't change an
existing function. That's a big difference, and leaves a LOT of room for
growth and overall change.
> I'll mull on this a bit and see if I can come up with a [good]
> proposal to deal with the problem. I had also tossed out another
> possibility, saying "Another solution is to just have four numbers?"
> But haven't really thought that one through carefully.
We'd have releases like:
1.1.0.0
1.1.1.3
1.1.4.1
1.2.0.3
1.2.1.1
2.3.0.4
2.3.1.0
Note that the second part is monotonically increasing, as that would be
the major API version.
Dunno about it altogether tho... I certainly haven't thought on it :-)
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by kf...@collab.net.
Greg Stein <gs...@lyra.org> writes:
> You have to have a number to discriminate between "break compat" and "not
> break", yet your proposal conflates those. Thus, you can never tell.
>
> Frankly, I'd like to request that you put a LOT more thought into the
> problem before making any kind of proposal or suggestion. I put a ton of
> thought into the rules APR and we are using now, with a lot of great ideas
> incorporated from Havoc Pennington's document. It is somewhat annoying to
> get drive-by suggestions / proposals that don't appear to have the same
> depth of thinking and have some real issues with them.
>
> Stop, think, and then post. I understand that you're possibly seeking to
> build a proposal organically with the other developers on this. I'd still
> ask for a well-thought proposal first, simply to avoid the long churn on
> the list for a topic that (IMO) is pretty well thought thru (with the
> caveat that some people want a "feature version" somewhere).
Fair enough -- that's an accurate description of the process I was
aiming for, but "organic" doesn't have to mean "compost heap".
I do think we have a real problem here. We can't change APIs without
calling it 2.0, yet we've reason to believe we'll want to fix up some
APIs *before* we have enough new features to justify calling it 2.0.
I'll mull on this a bit and see if I can come up with a [good]
proposal to deal with the problem. I had also tossed out another
possibility, saying "Another solution is to just have four numbers?"
But haven't really thought that one through carefully.
In the meantime:
I'd like to know if other people agree we have a problem here,
regardless of the eventual solution.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Stein <gs...@lyra.org>.
On Thu, Jan 08, 2004 at 04:48:24PM -0600, kfogel@collab.net wrote:
>...
> It seems to me like we have four concepts conflated in three numbers:
>
> a. Major feature additions
> b. API changes
> c. Changes that break binary compat
> d. Changes that maintain binary compat.
>
> Currently, (a) and (b) live in one number, the major version, and the
> others have their own numbers. My reshuffling gives (a) and (b) each
> their own number, and puts (c) and (d) in one number, the patch
> level.
You have to have a number to discriminate between "break compat" and "not
break", yet your proposal conflates those. Thus, you can never tell.
Frankly, I'd like to request that you put a LOT more thought into the
problem before making any kind of proposal or suggestion. I put a ton of
thought into the rules APR and we are using now, with a lot of great ideas
incorporated from Havoc Pennington's document. It is somewhat annoying to
get drive-by suggestions / proposals that don't appear to have the same
depth of thinking and have some real issues with them.
Stop, think, and then post. I understand that you're possibly seeking to
build a proposal organically with the other developers on this. I'd still
ask for a well-thought proposal first, simply to avoid the long churn on
the list for a topic that (IMO) is pretty well thought thru (with the
caveat that some people want a "feature version" somewhere).
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by kf...@collab.net.
Justin Erenkrantz <ju...@erenkrantz.com> writes:
> FWIW, I thought that the most aggressive estimates on dev@svn for a
> 2.0 were at least several years away...
There hasn't been any consensus on it, AFAICT..
> > http://apr.apache.org/versioning.html are maybe a bit too strict? I
> > feel like I want to move everything down one notch: major version
> > number change means major new features; minor version means same basic
> > features, but possible API changes; patch level means bug fixes and
> > small stuff.
>
> I think that's only reshuffling the deck chairs...
Well, not quite.
The current release number system forces us to use major version
increments for API changes. Unfortunately, the world at large assumes
that a major version increment also means major new functionality. In
other words, we have no way to introduce an API change without also
either introducing major new features, or disappointing users who
expect "more" from a 2.0.
It seems to me like we have four concepts conflated in three numbers:
a. Major feature additions
b. API changes
c. Changes that break binary compat
d. Changes that maintain binary compat.
Currently, (a) and (b) live in one number, the major version, and the
others have their own numbers. My reshuffling gives (a) and (b) each
their own number, and puts (c) and (d) in one number, the patch
level.
Another solution is to just have four numbers?
> I don't disagree, but the binary contract means a lot to us - perhaps
> there's a disconnect on whether we should even have binary compat
> rules? That might explain why there's been frustration on a bunch of
> proposed API changes. There are those of us (incl. myself) who realize
> that any warts in the API can't *really* be fixed if they make it into
> 1.0.
Oh, I realize it too. That's why I'm beginning to think that it's our
contract that's the problem...
> I'd personally also have no problem with running through major version
> numbers at a higher rate than previously suggested. But, that's been
> shouted down a number of times, I think.
I couldn't tell -- didn't feel a consensus on it, but hey, maybe I
missed something :).
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
--On Thursday, January 8, 2004 4:24 PM -0600 kfogel@collab.net wrote:
> about this. But I also think 2.0 is not too long to wait for such a
> change -- it doesn't have to be infinitely far in the future, if we
> feel there's a lot to change.
FWIW, I thought that the most aggressive estimates on dev@svn for a 2.0
were at least several years away...
> http://apr.apache.org/versioning.html are maybe a bit too strict? I
> feel like I want to move everything down one notch: major version
> number change means major new features; minor version means same basic
> features, but possible API changes; patch level means bug fixes and
> small stuff.
I think that's only reshuffling the deck chairs...
> I'd like to be able to release something soon (like, six months) after
> 1.0, that fixes API problems which were only discovered by virtue of
> 1.0 being out in the world. Would be nice to call that new thing
> "1.1" or "1.2", whereas "2.0" would imply huge new features (which
> wouldn't be the case).
I don't disagree, but the binary contract means a lot to us - perhaps
there's a disconnect on whether we should even have binary compat rules?
That might explain why there's been frustration on a bunch of proposed API
changes. There are those of us (incl. myself) who realize that any warts in
the API can't *really* be fixed if they make it into 1.0.
I'd personally also have no problem with running through major version
numbers at a higher rate than previously suggested. But, that's been
shouted down a number of times, I think.
> There's no reason why we can't discuss this while 1.0 stabilizes...
Sure. -- justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases
Posted by Greg Stein <gs...@lyra.org>.
On Fri, Jan 09, 2004 at 11:57:18AM -0500, Greg Hudson wrote:
> On Fri, 2004-01-09 at 00:44, kfogel@collab.net wrote:
> > So why are we trapping ourselves into this?
>
> If we expect our API to be successful, then we should expect that when
> we make an incompatible API change, it will take a while--possibly
> months or years--before all interesting third-party programs are updated
> to use the new API. gnucash still hasn't finished porting to GNOME 2.
Agreed.
> Therefore, when we make an API-breaking release, we need to paint a
> bright red flag on it which tells people not to upgrade by replacing the
> old version of svn, but instead to co-locate the new version with the
> old version.
Agreed, and I'll note that the versioning guidelines are defined in such a
way as to *enable* colocation of the libraries. There can only be one
command line, but the libraries and include headers can sit right next to
each other without problems. (IOW, the stuff that third-party apps need)
> With your scheme, there is no such bright red flag; not only would the
> initial version number not change, but a middle version number change
> *might or might not* signal an incompatible API change.
Yup.
And note that going from 1.x to 2.x implies a serious API breakage. I
can't see us doing that in the next year. Adding APIs? Sure. But breaking
existing ones... no.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Hudson <gh...@MIT.EDU>.
On Fri, 2004-01-09 at 00:44, kfogel@collab.net wrote:
> So why are we trapping ourselves into this?
If we expect our API to be successful, then we should expect that when
we make an incompatible API change, it will take a while--possibly
months or years--before all interesting third-party programs are updated
to use the new API. gnucash still hasn't finished porting to GNOME 2.
Therefore, when we make an API-breaking release, we need to paint a
bright red flag on it which tells people not to upgrade by replacing the
old version of svn, but instead to co-locate the new version with the
old version.
With your scheme, there is no such bright red flag; not only would the
initial version number not change, but a middle version number change
*might or might not* signal an incompatible API change.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by kf...@collab.net.
Greg Stein <gs...@lyra.org> writes:
> No. Those guidelines are necessary to create some kind of sanity in the
> upgrade/compatibility process.
Sure, I agree we need *a* guideline for the process. I'm asking, is
*this* guideline the best, or is there a better one for our purposes?
> If you upgrade SVN from 1.0 to 1.7, then all applications will continue to
> function properly. No need to update them. Any 1.x release provides all
> the entry points, signatures, and semantics of the prior 1.x releases.
>
> On the other hand, if you create an application that requires
> functionality from 1.4, then you will need to update that SVN 1.1
> installation to 1.4. But this is a safe thing to do, per above. That
> upgrade will not break other applications.
Okay, you're explaining the current guidelines. But as long as
there's *some* guarantee, where one can look at two version numbers
and know the degree & kind of difference, that will be just as good.
For example:
If you upgrade SVN from 1.2.3 to 1.2.4, all applications will
continue to function properly. But maybe if you upgrade from 1.2.3
to 1.3.1, that won't be the case.
That's a different guideline from what we're currently using, but it's
perfectly consistent. The APR versioning scheme is just one of many;
we're free to use another that suits us better.
> Part of the problem here is the conflation of using the version number to
> describe feature enhancements ("2.0 has a lot of wicked cool new
> functionality") and binary compatibility ("2.0 has a few minor feature
> enhancements, but the API was drastically revamped").
Yup, that's what I said too.
But that conflation is inevitable. It is the very reason why we'd be
reluctant to release 2.0 (say) six months after 1.0. Even though we
might have a lot of API changes batched up, we'd feel there was
something wrong in releasing 2.0 that quickly -- we'd feel we'd look
bad, and we'd be right. 2.0 should include major new features.
So why are we trapping ourselves into this? We could separate API
breakages from wicked cool new functionality, and then we could make
each kind of release when it was ready, instead of waiting for when
both are ready (which always means delaying one of them).
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: API-changing releases was Re: concerns about issue #1682
Posted by Greg Stein <gs...@lyra.org>.
On Thu, Jan 08, 2004 at 04:24:56PM -0600, kfogel@collab.net wrote:
> Justin Erenkrantz <ju...@erenkrantz.com> writes:
>...
> > Once we hit 1.0, you can't change any existing API prototypes until 2.0.
> >
> > So, say, if we change our parameters to svn_client_blame, we have to
> > have the old version as svn_client_blame and the new entry point as
> > svn_client_blame2 (or something like that to make the names different).
>
> Yah.
Right.
>...
> Am I the only one who is beginning to feel that the requirements at
> http://apr.apache.org/versioning.html are maybe a bit too strict? I
No. Those guidelines are necessary to create some kind of sanity in the
upgrade/compatibility process.
There was a post today that said something like this (I'll respond to it
directly in a bit):
"but if I upgrade SVN, then wouldn't I also have to upgrade all my
clients? [similar to the case of upgrading a client necessitating an
upgrade of svn]"
The answer is that upgrading SVN does *not* force an upgrade on the
clients. That is the whole reason for the design.
If you upgrade SVN from 1.0 to 1.7, then all applications will continue to
function properly. No need to update them. Any 1.x release provides all
the entry points, signatures, and semantics of the prior 1.x releases.
On the other hand, if you create an application that requires
functionality from 1.4, then you will need to update that SVN 1.1
installation to 1.4. But this is a safe thing to do, per above. That
upgrade will not break other applications.
> feel like I want to move everything down one notch: major version
> number change means major new features; minor version means same basic
> features, but possible API changes; patch level means bug fixes and
> small stuff.
I disagree. :-)
Part of the problem here is the conflation of using the version number to
describe feature enhancements ("2.0 has a lot of wicked cool new
functionality") and binary compatibility ("2.0 has a few minor feature
enhancements, but the API was drastically revamped").
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org