Release Management Versioning Scheme (was Re: [ApacheDS] Big Bang Cleanup)

[Alex Karasulu <ak...@apache.org>]

Hi all,

I just wanted to clarify some points about the voted upon policy for
releases and versioning.
It seems as though we have a lot of confusion and questioning about the
present scheme
which was restated below.

On 9/29/07, Alex Karasulu <ak...@apache.org> wrote:
>
> Our model is simple.
>
> 1). Start an experimental branch as the main branch of development (x.5branch)
> 2). Add new features and do some "feature releases" for early access to
> these features i.e. x=1
>      - 1.5.0
>      - 1.5.1
>      - 1.5.2
>      ...
> 3). Feature Freeze: freeze the addition of new features to begin to
> cleanup and stabilize
> 4). Release next major release candidates (x+1).0.0-RCy suffix with bug
> fixes only ie.:
>      - 2.0.0-RC1
>      - 2.0.0-RC2
>      - 2.0.0-RC3
>      ....
> 5). Release final major version i.e. 2.0.0
> 6). Copy this branch into branches area as 2.0 branch and do "bug fix"
> (ONLY) releases
> 7). Designate trunk as new experimental branch in this example 2.5 with
> next feature release 2.5.0 etc ...
>

Almost every time we get a new person on the team we start talking about
changing the scheme.
I'm fine with doing this since it improves what we have place but we cannot
be doing it as frequently
as we do.  Also I want to address this and other concerns in this email
regarding this scheme as well
as how it may change in the future with the introduction of modularity and
plugability.

First I heard many complaints about keeping having a stable release branch
and an experimental release
branch.  There is some natural frustration with doing this (I have it too)
but we have to understand why
many software projects take this approach:

1). stable releases only fix bugs to prevent further destabilization
2). by not introducing new features into stable releases ancillary
byproducts like documentation can also stabilize
3). less variables are introduced and less has to be tracked in stable bug
fix releases
4). constraints like backwards compatibility are addressed in stable
branches
      - API's can be guaranteed not to change in stable branches
      - Partition Formats
      - Configurations etc.
5). Performance tuning can also be done in stable release branches as long
as they do
    not violate the other points above.

This lock down is needed or else we have chaos. We must wear a different hat
when we go into stable
branches to make bug fixes.

On the other hand we also need evolution.  New features and refactoring is
needed to improve the server
and progress on a roadmap.  You don't have roadmaps on stable bug fix
branches:

1). New features introduced in experimental branches with feature releases
2). Refactorings help change the architecture
3). Developers can be more liberal with changes without stressing over
screwing users since
     we are clear to users up front about what that branch is there for.
4). Users have a chance to test new features and provide feedback so we can
improve
     upon them before the final major release.  This is why feature releases
are done.

I'm sure there are more things we can add to both the lists above.  Now
let's discuss the numbering scheme.
Some history first.

Early on in this project we used the same versioning scheme as Linux did in
the past.  Odd minor numbers
represented experimental branches while even minor numbers represented
stable bug fix branches.  Here are
some fictitious examples:

Stable Branches              Experimental Branches
------------------------              ---------------------------------
0.6                                      0.7
0.8                                      0.9
1.0                                      1.1
1.2                                      1.3
2.6                                      3.7

Linux used to use this scheme in the past but dropped it.  This is
predominantly due to the fact that the Linux
community is trying to adapt to be able to compete in the desktop market
when before it was more considered
a server side operating system.  They have changed the scheme to where bug
fixes and features are intermingled
now.  This is because they need to react quicker to changes in hardware on
desktop/laptop systems to provide
functional drivers.  The server hardware market does not change as rapidly
for obvious reasons (stability) that most
are aware of.

We chose this scheme for ApacheDS (does not apply to Studio) because
ApacheDS is a server product. Hence
a clear demarcation between stable and experimental branches are critical.
Also I don't think we want any more
branches to have to manage than this.  With every new stable branch the old
stable branch reaches it's end of
life to reduce the overhead for the team.

When Chris Custine came on board he had a good idea to not use Odd/Even
schemes but to jump from one
major revision to the next with a X.5 experimental branch in between.  This
is essentially the same scheme but
the numbering is different.  I think Chris and others realized we would be
stuck with a very mature product that
had low version numbers giving it the impression of being not so mature.
This is a good point but for me personally
I liked the idea because it sends a clear message to our users across stable
major versions instead of stable minor
versions: "hey look out a lot has changed".  I like that message because it
affords us more freedom to evolve the
server in the experimental branch between the two stable branches.  So we
decided as a group to just adopt this
change to how we version releases.  Examples below:

Stable Branches              Experimental Branches
------------------------              ---------------------------------
1.0                                      1.5
2.0                                      2.5
3.0                                      3.5
4.0                                      4.5

etc ..

Now people are complaining again but some are valid concerns.  One complaint
is that with this scheme we
cannot get stable releases with all the nice features into the hands of the
users fast enough.  To some degree
this is something I worry about myself but then I think of the alternatives
and cannot find a good solution.

One thing we can do is speed up the process while introducing less new
features in experimental branches.  This
lessens the concern above but it also creates more maintenance overhead for
us since we're going to have to change
the site, and the documentation to keep up.  But this is not black and white
so we can sense and respond.  The
roadmaps in the experimental branches can be designed to throttle this
process.

Modularization and Plugin Releases
---------------------------------------------------

At some point when we have better modularization that allows for plugins in
the server we're going to be able to
have much more flexibility but with some hotspots that become even less
flexible (interfaces and APIs).  The
release management and version dynamics may change completely at this
point.  Until then I am not going to
worry about it but here are some facts, ideas and/or possibilities.

We're going to still need to have a stable and experimental branch for the
core server.  It might be nice if
plugins followed similar schemes and matched major numbers but I don't know
if they have to or should.
Plugins just need to know that interfaces in the server will be stable so
they can work properly.  OSGi's version
based bundle loading will be interesting when considering these matters.
Also note there will be two classes
as well of plugins: optional and mandatory system bundled.  So some will
need stricter management than
others.  Incidentally even if the same major version numbers are used in
plugins they don't have to align minor
and micro numbers so they don't have to be in sync.  This is the biggest
freedom we gain I think.

Also note we can release plugins at different rates without doing server
releases.  This is huge.

Anyways I think others probably have ideas on this matter so feel free to
chime in.

Alex