[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Things you must consider for version numbering

From: Justin Erenkrantz <justin_at_erenkrantz.com>
Date: 2003-12-20 10:15:42 CET

--On Friday, December 19, 2003 7:52 PM -0500 Greg Hudson <ghudson@MIT.EDU>

> You've proposed a constraint: our library ABI versions should be all
> tied together, that ABI version should also be tied to the Subversion
> release number, and that snapshots, testing releases, and and private
> builds must adhere to the version-numbering constraints as stable
> releases. This constraint has some far-reaching implications for a
> project with multiple libraries and with non-library components:
> * We release Subversion X.Y.Z and then make massive (possibly even
> incompatible) changes to the command-line client, or add a significant
> new feature, but do not change the library API. We must now choose
> between releasing Subversion X.Y.Z+1 even though there are significant
> new features, or releasing Subversion X.Y+1.Z and forcing unnecessary
> library upgrades.

If we are really making incompatible changes to our command-line client, why
would we only be bumping the patch level? That seems wrong to be advocating
from the users' perspective. (I've been asking how do the non-API things
trigger a version bump. I think some of them do - such as schema changes,
incompatible protocol changes, etc. No one seems interested in that yet.)

I want a clear contract with third-parties and our users about what their
expectations should be regarding major, minor, and patch versions. My largest
complaint (that I've repeated a number of times here) is that the Mozilla
model that has been advocated does not indicate how 'big' of a change one
version is to the next. Mozilla (and Linux and FreeBSD to some extent)
side-step compatibility as they don't really have binary compatibility.
Mozilla just uses the old Netscape plugin API which, AIUI, doesn't change
because doing so would be harmful to their installed base.

I think the largest benefit of Subversion over CVS will be its extensibility.
I think we're in agreement about that, but I also want it to be clear how to
manage changes in the 'core' distribution released from tigris.org. I'm just
not sure that we can splice apart the versioning into things that we aren't
decomposing ourselves.

Let me explain with an analogy:

The model that Keith Packard has been proposing for X is that every library is
a stand-alone release. There will be no 'X' releases any more - only libFoo
that is a part of X. Your proposed model with separate versioning makes sense
*if* we distribute all of the libraries independently. Keith's perspective is
that it'll stabilize over time, so the initial anarchy and confusion caused by
the split will eventually stabilize and produce something useful.

We did discuss in depth over in httpd-land about switching to that model. It
wasn't really positively received because of the differences between X and
httpd. I think some of the same rationale applies here in Subversion.

As in httpd, the Subversion 'core' is maintained by one group of people
(namely the full committers). In httpd-land, we felt that partitioning out
the components into discrete releases would harm the community and
maintainership. It'd create fiefdoms that we wanted to avoid.

Furthermore, over in httpd-land, we felt that if we're viewing the entire
codebase as one complete system, then there's problems with having everything
be disjoint. Are we planning to support (as a community) the individual
components or the entire collection? We felt that everything in an httpd
release is 'together' - that is, if one part is stable, so is the rest. I
think the same could be said about Subversion.

Now, remember that Keith's goal was purposely to create fiefdoms as that's
certainly better than what X has now. Keith also admitted that it comes at a
price: inter-operability between the libraries is going to be a *big* problem.
How do you make sweeping changes if there are 20 different releases that
constitute X? You could have a flag day and try to convince all of the
fiefdoms to change; but there's human scalability problems there. I think
that that the Subversion developers would want a unified vision of how the
libraries should operate that is consistent across libraries.

Finally, I'd like for TortoiseSVN (or any other third-party) to finally say,
"We're compatible with any Subversion 1.x install." Given your choice, what
would you say that the TortoiseSVN folks should ask for? Is it "we're
compatible with libsvn_wc 1.0, libsvn_ra 1.0, libsvn_client 1.0, etc." So, at
what point, does TortoiseSVN *need* to produce a new release? Is it
Subversion 1.1? Is it Subversion 1.2? Is it Subversion 2.0? Do we know?

If you want to go the route of only relying upon an individual library's
version, then I think we must go Keith's route and split the release up - make
every library stand on its own and released on its own. Packaging things up
as a collection and saying, "Oh, the *real* version information is hidden
inside of this meta-version; you must look at these twenty different libraries
to figure out if you're third-party app is compatible" strikes me as we can do
better than that.

> * We release Subversion X.Y.Z and then fix a security hole by adding a
> new library function. We must release Subversion X.Y+1.Z or (X.Y+2.Z if
> we do even/odd) even though we only made a single targeted bugfix.

If we stick to the versioning API advocated by APR, perhaps. If it's that
critical, I think we could find a way to create a release that didn't require
a minor bump. Don't export the new function, or whatever. *shrug* We've
done that in httpd.

Yet, our deltas from 1.0->1.1/1.2 could be 'minor' and frequent. Note that's
also what we're doing right now: 0.34->0.35. That's goodness, and something I
think httpd hasn't figured out how to do yet - what's the 'right' size of
change between minor versions? I'd prefer Subversion to produce new 'minor'
versions every few months. Don't bother backporting to the previous minor
version, but rely upon solid versioning rules to manage expectations as we
produce new minor releases that add functionality.

I think a huge disparity in this conversation is how often we expect to
produce releases and of what type. Are we going to produce 1.0 and then
immediately do 1.0.1, 1.0.2, 1.0.3 every two weeks. And, in six months, will
we produce 1.1 (or 1.2 if we follow even/odd)? Or, is the time between 1.0
and 1.1 much shorter?

If we say that we're going to be producing x.y+1.z releases every month, do we
really need odd/even? Perhaps not. If we're saying longer than six months,
then yes I think we must have an unstable versioning scheme.

> * We add a function to libsvn_client, but do not make a change to the
> server. The server's API version must also be bumped, forcing
> unnecessary library upgrades upon people who update server binaries.

Why? The people running the server wouldn't update. I don't understand why
the library upgrade is a concern here.

> * If we do not relax the policy for trunk snapshots, then we will have
> bizarrely spaced releases (e.g. stable 1.0.0 followed by unstable 1.1.0,
> 1.3.0, and 1.5.0, followed by stable 1.6.0, if we use odd-even).

I don't understand this scenario. Where did 1.2 and 1.4 go?

Trunk snapshots are just that: 1.3.0, 1.3.1, 1.3.2, 1.3.4. As I see it, the
binary compatibility expressed in the trunk snapshots are relative to the last
stable version - not to the last trunk snapshot. The unstable versions don't
have a 'fixed' contract, yet they are supposed to be fixed to the last
'stable' release. The 1.3.x would represent the current API proposed for 1.4
- it should be binary-compatible to 1.2 and adds new features that will be
'frozen' for 1.4.

If a change goes into the trunk that causes binary compatibility to be lost,
it's 2.0. Note that this was a major point of contention when adopting both
the APR and httpd rules - what do we do on major version bumps? How do we do
a dev cycle for that? Both times, we decided to punt and deal with it when we
had to. (At one point, we said that 0 should be considered odd; which isn't
unreasonable but isn't very user-friendly, I think. Arrays start at 1 was a
good argument for why it'd pass muster!)

> * If we do not relax the policy for private builds, then we must bump
> the trunk middle version every time we add a new library function, and
> our middle version numbers for releases of any kind would likely be
> spaced very far apart (stable 1.0.0 followed by unstable snapshots
> 1.13.0, 1.33.0, and 1.85.0, followed by testing releases 1.99.0, 1.99.1,
> and 1.101.1, followed by stable 1.102.0).

Again, unstable releases (or anything derived from trunk) would not have
binary compatibility rules in place relative to each other, but they *should*
work against the previous stable version per binary compatibility rules.

Remember my key constraint is that private builds have *some* x.y.z version
number attached. If y denotes it is 'unstable', then it means that it should
be binary compatible to y-1 and should be the progress towards the y+1 API.

> Confusingly, you have typically argued for this constraint in response
> to specific aspects of other people's proposals, even though accepting
> the constraint would mean essentially scrapping any such proposal
> (Karl's or mine) and starting over from the APR versioning system.

I don't understand.

> I think it's helpful because:
> * Stable releases are versioned according to whether they have made
> major changes, minor improvements, or only bugfixes relative to previous
> releases, allowing people to make reasoned upgrade decisions without a
> lot of research.

And those are arbitrary decisions. You and I may disagree on what is a major
change, what is a minor change, and what is a bugfix. I want to remove any
arbitrary decisions from the versioning process as we'd just get bogged down
by people disagreeing on what is 'big' or not. If the versioning is tightly
bound to the bundled API, then I think there's little room for discussion
about what the next version should be called; and it's clear what a version
bump means. In my proposed model, the only thing left is to define what
*else* causes version bumps (i.e. repos schema, etc, etc.).

> * Unstable snapshots, testing releases, and private builds clearly
> indicate their source (trunk revision or branch and revision) without
> disturbing the namespace of stable releases.

As has been repeated several times by others, revision numbers (rXXXX) are not
practical for use by Subversion itself in reporting a version. And as I have
said before several times, I don't believe there is a meaningful way to map
the monotonically-increasing revision numbers into versions that indicate any
type of compatibility.

> I didn't invent this kind of versioning. It differs from dozens of
> other projects only in the details. (The same could be said of Karl's
> proposal, of course.)

And, I think there are issues if we go down the 'ad hoc' versioning system you
are advocating. It'll be unclear when to upgrade your third-party apps.
You'd be breaking apps built on SVN from one 'stable' release to another
because some constituent library changed, but it was not viewed as a 'major'

If I've learned anything from httpd, it's that a strong contract that is clear
to everyone is essential. We screwed that up with httpd-2.0 at first, and
only figured it out after we got nasty comments from people complaining about
the moving target that was 2.0. I believe your versioning system is going to
open Subversion up to the same criticisms. -- justin

To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Dec 20 10:16:35 2003

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.