[rfc] six-month stable release cycles

[Martin Pool]

A longer stable cycle has often been requested.  I think we should do
it, now, along the lines of this document.   (It's in devnotes and
also as a pdf for those who like it that way.)

-- 
Martin <http://launchpad.net/~mbp/>

***********************
Bazaar Six-Month Cycles
***********************

:status: Draft proposal, as of 2009-07
:blueprint: <https://blueprints.launchpad.net/bzr/+spec/6m-cycle>

The Problem Situation
*********************

Bazaar makes a release every month, preceded by a one-week
release-candidate test.

In any release we may fix bugs, add formats, change the default format,
improve performance, add new commands or change command line behaviour,
change the network protocol, or deprecate APIs.  We sometimes also
introduce new bugs, regress existing behaviour or performance, remove
existing features or formats, or break behaviour or APIs depended upon by
plugins, external programs or users.

Some users are happy upgrading every month and consider the overall
positive balance of changes is worth some amount of churn.  But there are
some serious problems:

* You cannot get bug fixes without also getting disruptive changes.

* Bazaar is seen as unstable.

* Many releases cause some plugin breakage.

* One month is not a very long window for dependent programs or systems
  to catch up to changes in Bazaar before the release goes out of date.

* There's no clear indication to distributions which version they should
  package.

* If people (or their distributions) just pick an arbitrary version, they
  may all be on different arbitrary versions, therefore they will have
  different behaviour and different bugs, and sometimes interoperation
  problems.

* Any effort we, or distributors, wanted to put into backporting fixes
  would be dissipated across many possible backport target releases.

The Proposal
************

Bazaar will make a major release every six months, which will be supported
at least until the time of the next major release.  During this support
period, we'll make incremental releases which fix bugs, but which do not
change network or disk formats or command syntax, and which do not require
updates to plugins.

We will also run a development series, which will become the next major
release.  We'll make a beta release from this every four weeks.  The
beta releases will be as stable as our current monthly releases and
completely suitable for everyday use by users who can tolerate changes
from month to month.

Having the stable series isn't a reason to cut back on QA or to make the
trunk or development releases unstable, which would only make our job
harder.  We keep our trunk in an always-releasable state, and that should
continue: any beta release could potentially be supported in the long
term, but we identify particular releases that actually will be supported.


Schedule
--------

::

 2.0 --- 2.0.1 -- 2.0.2 -- ...
  \
   +--3.0beta1 -- 3.0beta2 -- ... -- 3.0rc1 -- 3.0 -- 3.0.1 -- ...
                                                \
                                                 \
                                                  +-- 4.0beta1 ...


Starting from the date of a major release:

At four-week intervals we make a new beta release.  There will be no
separate release candidate, but if a serious problem is discovered we may
do the next beta ahead of schedule or make a point release.  There will be
about five or six releases in that series.

In parallel with this, bugs targeted to the previous major release are
merged into its branch.  We will make bugfix releases from that branch as
appropriate to the accumulation of changes, perhaps monthly, perhaps more
often if there are serious bugs, perhaps much less often if no new changes
have landed.

We will then make a release candidate for the next major release, and at
this point create a release branch for it.  We will iterate release
candidates at approximately weekly intervals until there are no bugs
blocking the final major release.

Compared to the current process this has approximately the same amount of
release-related work, because the extra releases from the stable branch
are "paid for" by not doing RCs for the development series.

We will synchronize our major releases with Ubuntu, so that they come out
in sufficient time for some testing and margin of error before Ubuntu's
upstream freeze.


Names and Numbers
-----------------

Major releases (2.0)
    The big ones, every six months, intended to ship in distributions and
    to be used by stability-oriented users.

Release candidate (2.0rc1)
    A preview of a major release, made one or a few weeks beforehand at
    the time the release branch is created.  There should be few if any
    changes from the rc to the stable release.

Bugfix releases (2.0.1)
    Based on the previous major release or bugfix; contains only bugfixes
    and perhaps documentation or translation corrections.

Stable series
    A major release and its descendant bugfix releases.

Stable release
    Either a major release or a bugfix release.

Beta release (3.0beta1)
    Made from trunk every month, except for the month there's a major
    release.  Stable and suitable for users who want the latest code and
    can live with some changes from month to month.

Development series
    The development releases leading up to a stable release.


Bug Work
--------

Bug fixes should normally be done first against the stable branch,
reviewed against that branch, and then merged forward to trunk.

It may not always be easy to do this, if fixing the bug requires large
changes or the affected code is different in the stable and development
branches.  If the tradeoff does not seem worthwhile the bug can be fixed
only in the development branch, at least in the first instance.  If users
later want the fix backported we can discuss it.

Developers can merge the release branch into trunk as often as they like,
only asking for review if they're making nontrivial changes or feel review
is needed.


Feature and Performance Work
----------------------------

Features can be landed to the development branch at any time, and they'll
be released for testing within a month.

Performance bugs, although important, will generally not be landed in a
stable series.  Fixing performance bugs well often requires nontrivial
code changes or new formats.  These are not suitable for a stable series.

Performance bugs that can be fixed with a small safe patch can be
considered for the stable series.


Plugins
-------

Plugins that want to cooperate with this should make a series and a branch
that matches each bzr stable series, and follow similar rules in making
releases from their stable branch.  We'd expect that plugins will make a
release between the last development release of a series and the major
release candidate.

Within a stable series, anything that breaks any known plugin is
considered an API break and will be avoided.  Before
making each bugfix release, we'll test that code against important
plugins.

Within a development series, the focus is on helping plugin authors keep
up to date by giving clear error messages when an interface is removed.
We will no longer focus on letting old plugin code work with new versions
of bzrlib, which is an elusive target in Python.

This may mean that in cases where today a plugin would keep running but
give warnings, it will now fail altogether with an error.

In return we expect more freedom to change and cleanup bzrlib code without
needing to keep old code around, or write extra compatibility shims, or
have review turnarounds related to compatibility.  Some changes, such as
removing module-global variables, that are hard to do now, will be
possible to do safely.

Discussion of plugins here includes programs that import and use bzrlib
but that aren't technically plugins.  The same approach, though the
technical considerations are different, should apply to other extensions
such as programs that use bzr through the shell interface.



Data and Network Formats
------------------------

Any development release should be able to interoperate with the previous
stable release, and any stable release should be able to interoperate with
the previous stable release.  This is a minimum and normally releases will be
able to interoperate with all previous releases as at present.

Each major release will have one recommended data format which will be the
default.  This is not to say that every major release will change it;
they should change less often.

During a development series we may have a series of experimental formats;
towards the end of the development series we will mark one as stable and
target it to become the default for the upcoming major release.

There is no promise of compatibility between development releases.  In
general we will not break compatibility but it leaves the option open that
if something inserted in one development release turns out to be bad it
can just be removed in the next.  We will of course not leave users of
beta versions stranded: there will always be a way for them to move their
data forward.


Hosting Services
-----------------

The guarantees made above about format and network interoperation
mean that hosting services such as Launchpad, Savannah, FedoraHosted,
and Sourceforge could choose to run either the stable or beta versions.
They might find it useful to run the beta version on their own beta
server.


Simultaneous Installation
-------------------------

Some people may want to simultaneously install and use both a stable
release and development release.

This can be handled in various ways either at the OS packaging or the
Python level.  We don't propose to directly address it in the upstream
source.  (For example, we will not change the bzrlib library name from one
release to the next.)

The issue already exists with people who may want to use for example the
previous bzr release and the trunk.  There is a related issue that plugins
may be compatible with only some of the Bazaar versions people want to use
at the same time, and again that is something that can be handled
separately.


OS Distributions
----------------

OS distributors will be recommended to ship the bzr stable release that
fits their schedule, the betas leading up to that release during their own
beta period, and the bugfix releases following on from it.  They might
also choose to offer the beta releases as an alternative package.


Packaging
---------

At present we have three upstream-maintained PPAs containing Ubuntu
packages of Bazaar: ``~bzr-nightly-ppa``, ``~bzr-beta-ppa`` (rcs and
releases) and ``~bzr`` (ie stable).  We will keep these PPAs, and reorient
beta to contain the monthly beta releases, and the stable PPA to contain
stable releases, their release candidates, and bugfixes to those releases.

Some platforms with relatively less active packagers may choose to ship
only the stable releases.  This is probably better than having them only
intermittently or slowly ship the monthly releases.


Questions
*********

Do users actually want this?
    Apparently yes, because it's often requested and often raised as a
    problem.

Would this confuse users?
    It shouldn't, because it's a fairly standard scheme.

Won't it take more time to fix bugs in multiple places?
    It shouldn't, because we'll only do this when the stable bugfix seems
    economical.  When we fix bugs today in both trunk and release branches
    it normally does not take much more time.

What about bzr in Ubuntu LTS, with a five-year support life?
    Most bugs are either fixed within six months, or not fixed at all, or
    not very important, or fixed as part of a large rework of the code
    that would be too large to backport.  However, if there are fixes that
    are especially desired in an old release and feasible to do, we can do
    them without making a general commitment.

Will anyone test the beta releases?
    Probably yes, our most active users will run them, but if people would
    really rather not test them, forcing them is not helpful.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: release-cycles.pdf
Type: application/pdf
Size: 74396 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20090729/4d10ae44/attachment-0001.pdf