Subject: bug#13578: [IMPORTANT] A new versioning scheme for automake releases, and a new branching scheme for the Git repository

From: Stefano Lattarini <[email-masked]>
Date: Thu, 31 Jan 2013 14:01:10 +0100

On 01/30/2013 04:30 AM, Daniel Herring wrote:
> On Mon, 28 Jan 2013, Stefano Lattarini wrote:
> 
>> Feedback, opinions, objections?
> 
> There was a lot to read, and I confess to not giving it full justice.
> 
> Others have already extolled the virtues of backwards compatibility.
> 
> 
> Regarding some "why" questions, here's the manual entry on how versioning
> is used today.
> 
> http://www.gnu.org/software/automake/manual/html_node/API-Versioning.html
>
And this is a good and valid policy, but one I have unfortunately broken
in practice during the last year or so.  This proposal should address that
breakage, restoring sane versioning semantics.

> 
> As far as I can tell, the current proposal boils down to "bump the major
> version more often".
>
The real issue is that the major version in currently being bumped already
in practice (big new features, backward-compatibility broken in some
respects), without this being reflected in the "true" version number
("hey, why have you broken backward-compatibility from 1.12 to 1.13?
What is wrong with you?").  And while this is mostly my fault, fixing
it will benefit everyone (in addition to healing my ego, of course :-)

> That can work, but I'm not quite sold on it.  I like when a major bump
> means "wake up and reread the docs before upgrading" and minor bumps
> mean "upgrade casually".
>
This is a good user-level approach that the new versioning scheme would
automatically encourage.

>  (and aggregate changes to minimize major bumps and make them more
> worthwhile)
> 
And similarly, this is a good developer-level approach that the new
versioning scheme would automatically encourage.

> Here are a couple "standards" for versioning.
> 
> http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
> http://semver.org/
> 
This last resource seems nice, but alas, adding support for "VERSION+BUILD"
development versions might prove a little more problematic than I'd like (of
course, parched are very very welcome).

> The general principle being A.B.C decodes to something easy like
> A = new API, breaking changes requiring human intervention
> B = same API, maybe with added options, mostly just recompile
> C = just bugfixes, documentation tweaks, packaging, etc.
> 
> For example, a deprecation warning bumps B, but actually removing
> the deprecated functionality bumps A.
>
Indeed.  Something that I have guiltily failed to do in the recent
Automake developement process.

> As for branching, if every release is tagged, and you want to
> apply a bugfix to release A.B.C, why not just create a maint-A.B
> branch or the like?
>
For older versions, that is indeed the sanest approach.  But I think
we should also accept the fact that the "last-released" minor version
is going to need mostly-frequent fixes (most of the will probably be
suggested by the work on the next minor release), so that having a
branch already and explicitly devoted to the purpose of implementing
such fixes is the best and simplest setup.

> Delay creating branches until they are needed.  I wasn't seeing the
> need for the complex branching details.
>
I don't think my "new" branching scheme is actually complex.  May I
ask what makes you label it as such?

> 
> I agree its nearing time for a "2.0" release; there has been talk
> of removing several now-deprecated functions and making other
> major changes (e.g. parallel testing).
>
Making the "parallel harness" a default has already been implemented
in 1.13; something I now quite regret not having delayed to a new
major version.

> Would it be possible to start collecting these into a preview/beta
> release and leave the "1.0" series with its current API and
> behaviors?  Just a thought.
>
Ideally, yes; but the time for a 2.0 will only come in a year or so
(as we want to give the existing non-fatal deprecation enough time
to brew, and there are also plans for several new minor versions in
the meantime).  So there is no need to hurry with previews etc.

> I've done the build system for several projects I'm no longer
> associated with.  It would be nice if the people who inherited
> them don't have to rework them for a few more years.  A major
> version change (again, small numbers) might motivate distributions
> to keep both around for a while.
>
Indeed; I hadn't thought about that explicitly when writing my
proposal, but you making a good point (and also offering a good
"between-the-line" suggestion: don't release new major versions
too often).

> Hope that helps,
> Daniel

Thanks,
  Stefano