Rev 4609: (mbp) add six-month release policy and tweak release developer docs in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Aug 14 09:45:28 BST 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4609 [merge]
revision-id: pqm at pqm.ubuntu.com-20090814084522-m4bomm9pj2ne1kw1
parent: pqm at pqm.ubuntu.com-20090814054927-k0k18dn46ax4b91f
parent: mbp at sourcefrog.net-20090814062737-84udrv5pv8tjb37k
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2009-08-14 09:45:22 +0100
message:
(mbp) add six-month release policy and tweak release developer docs
modified:
doc/developers/cycle.txt cycle.txt-20081017031739-rw24r0cywm2ok3xu-1
doc/developers/releasing.txt releasing.txt-20080502015919-fnrcav8fwy8ccibu-1
doc/index.txt index.txt-20070813101924-07gd9i9d2jt124bf-1
=== modified file 'doc/developers/cycle.txt'
--- a/doc/developers/cycle.txt 2009-06-15 07:22:59 +0000
+++ b/doc/developers/cycle.txt 2009-08-12 06:43:36 +0000
@@ -1,16 +1,18 @@
-============================
-The Bazaar Development Cycle
-============================
-
-
-Overview
---------
-
-Bazaar makes a release every four weeks, with one release candidate one
-week before the final release. We may vary this schedule from time to
-time, amongst other things to respond to bugs reported in the release
-candidate or the final release. Nevertheless, we value a regular release
-and we will normally slip only for serious bugs or regressions.
+*********************
+Bazaar Release Cycles
+*********************
+
+:status: Current policy, as of 2009-08.
+:blueprint: <https://blueprints.launchpad.net/bzr/+spec/6m-cycle>
+
+
+Our users want easy access to bug fixes without other changes to the
+core product. They also want a Just Works experience across the full
+Bazaar ecosystem. To deliver the first and enable the second, we're
+adopting some standard process patterns: a 6 monthly release cycle and a
+stable branch. These changes will also have other benefits, including
+better availability of bug fixes in OS distributions, more freedom to
+remove old code, and less work for in packaging.
See also:
@@ -19,65 +21,318 @@
* `Releasing Bazaar <releasing.html>`_ -- the process for actually making
a release or release candidate.
-Longer-Term Planning
---------------------
-
-Work spanning multiple releases is typically tracked in the bug tracker,
-and summarized in <http://bazaar-vcs.org/Roadmap>.
-
-
-General Process
----------------
-
-We normally have one person acting as the release manager, who
-organizes development for the release and also actually makes the release
-tarball and posts announcements. It can be a different person from one
-release to the next.
-
-Our usual process is that one week before release we will make a release
-branch from the trunk. We do one commit to that branch to change the
-version number to 'rc1', and advance the trunk version to 'dev' for the
-next release.
-
-We then publish and announce this release candidate according to the
-process below. We then have a week of general testing of the rc,
-including some time for plugin authors to update their code for any
-changes.
-
-Normally no changes will be made on the release branch unless serious bugs
-or regressions are found, and the release manager decides they should be
-merged in. After one week, the release branch's version number is updated
-and it's published as the final release. If regressions or serious
-problems are discovered after the final release we may make an additional
-point release from that branch.
-
-The process or timing can vary if that seems appropriate in a particular
-case but we try to release on a regular four week cycle.
-
-The net effect is that the code gets some extra testing before release,
-and the trunk is always open for general development.
-
-
-Starting a Release
-------------------
-
-To start a new release cycle:
-
-#. Send mail to the list with the key dates, who will be the release
- manager, and the main themes or targetted bugs. Ask people to nominate
- objectives, or point out any high-risk things that are best done early,
- or that interact with other changes.
-
-#. Add a new "series" in Launchpad at <https://launchpad.net/bzr/+addseries>.
- There is one series for every *x.y* release.
-
-#. Add milestones to that series for the release candidate and the final
- release, and their expected dates.
-
-#. Deactivate old releases and their milestones.
-
-#. Update the version number in the ``bzr`` script, and the
- ``bzrlib/__init__.py`` file.
+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.
+
+* When in the past we've tried either stalling releases for particular
+ features, or having trunk frozen for some weeks, it causes churn and
+ waste. People rush features in, or already landed features wait a long
+ time to be released, or branches go out of date because they cannot
+ land.
+
+
+The Process
+************
+
+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.
+
+The trunk will never be frozen: changes that pass review, other quality
+checks and that are agreed amongst the developers can always be landed
+into trunk. The only restrictions will be on branches specifically
+targeted at a release.
+
+
+Schedule
+--------
+
+::
+
+ 2.0 --- 2.0.1 -- 2.0.2 -- ...
+ \
+ +--2.1beta1 -- 2.1beta2 -- ... -- 2.1rc1 -- 2.1 -- 2.1.1 -- ...
+ \
+ \
+ +-- 3.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.
+
+
+Regularity
+----------
+
+We value regular releases. We prefer to slip a feature or fix to
+a later release rather than to make a release late. We will normally only
+slip a release to fix a critical bug.
+
+
+Numbering
+---------
+
+The number for a six-month cycle is chosen at the start, with an increment
+to either the first field (3.0) or second field (3.1) depending on what we
+expect to be the user impact of the release. We expect releases that
+culminate in a new disk format or that require changes in how people use
+the tool will get a new major number. We can change (forward only) if it
+turns out that we land larger changes than were expected.
+
+
+Terminology
+-----------
+
+Major releases (2.0 or 2.1)
+ 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. We should avoid the
+ confusing phrasing "release candidate 2.0rc1 is released"; instead use
+ "available."
+
+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. The name of the format will indicate which release series (not
+specific release) it comes from: '2a' is the first supported format for
+the 2.0 series, '2b' the second, etc. We don't mention the particular
+release that introduced it so as to avoid problems predicting precisely
+when it will land.
+
+During a development series we may have a series of experimental formats.
+We will not leave people stranded if they test these formats, but we also
+won't guarantee to keep supporting them in a future release. If something
+inserted in one development release turns out to be bad it can just be
+removed in the next.
+
+
+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.
+
+Binary installers should use a version number like '2.0-1' or '2.0beta1-1'
+so that the last component just reflects the packaging version, and can be
+incremented if a new installer is made with no upstream source changes.
+
+
+Code Freeze vs Announcement
+---------------------------
+
+We will separate the code freeze for a particular release from its actual
+announcement, allowing a window of approximately one week for plugins to
+be released and binary installers to be built. On the date the
+announcement is published, people will be able to easily install it.
Weekly Metronome Mail
@@ -99,24 +354,71 @@
of certain things, etc.
-Starting the release phase
---------------------------
-
-When it's time to make the release candidate:
-
-#. We create a new pqm-controlled branch for this release series. The
- branch must be created by Robert Collins on the pqm server.
- This branch means that from the first release candidate onwards,
- general development continues on the trunk, and only
- specifically-targetted fixes go into the release.
-
-#. Register the branch at <https://launchpad.net/products/bzr/+addbranch>
-
-#. The revision at the start of that branch is `released
- <releasing.html>`_ as the first RC.
-
-
-
+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.
+
+Isn't this a step backwards to a slower, less-agile process?
+ No, our trunk stays releasable, and we ship every month. We're just
+ cutting out things that hold us back (continuous rather than episodic
+ API stability; RCs every month) and giving users what they demand.
+
+How about calling the monthly releases "milestone" or "next" not "beta"?
+ Those words are less scary but they also have less clear meanings.
+
+
+Expected Benefits
+*****************
+
+If this plan works, we'll expect to see the following changes. If they
+don't occur, we'll think again:
+
+* We see a distribution curve of users and bug reports across nightly, monthly
+ and stable releases, indicating that each has value.
+
+* API changes are easier or safer to make during beta periods, without
+ being held back by fears of compatibility or
+
+* The stable releases are actually stable and don't introduce regressions
+ or break plugins.
+
+* Many bugs are fixed in stable branches, without developers feeling this
+ is a waste of time.
+
+* Distributions ship the stable releases in their stable releases and the
+ bugfix releases in their bugfix releases.
+
+* Plugin authors follow this policy, making their own bugfix releases.
+
+* Users like it.
+
+References
+**********
+
+#. List thread "[rfc] six-month stable release cycles", July 2009.
..
vim: filetype=rst textwidth=74 ai shiftwidth=4
+
=== modified file 'doc/developers/releasing.txt'
--- a/doc/developers/releasing.txt 2009-06-15 22:35:00 +0000
+++ b/doc/developers/releasing.txt 2009-08-14 06:27:37 +0000
@@ -9,11 +9,26 @@
.. contents::
+
+Starting the release phase
+--------------------------
+
+When it's time to make the release candidate:
+
+#. We create a new pqm-controlled branch for this release series, by
+ asking a Canonical sysadmin.
+ This branch means that from the first release candidate onwards,
+ general development continues on the trunk, and only
+ specifically-targetted fixes go into the release.
+
+#. Register the branch at <https://launchpad.net/products/bzr/+addbranch>
+
+#. Make a release candidate.
+
+
Preparing the tree for release
------------------------------
-.. Was previously at http://bazaar-vcs.org/ReleaseChecklist
-
#. Make a local branch for preparing this release. (Only for the first
release in a series, otherwise you should already have a branch.) ::
@@ -47,6 +62,11 @@
./tools/check-newsbugs.py NEWS
+ (But note there can be some false positives, and this script may be
+ flaky
+ <https://bugs.edge.launchpad.net/bzr/+bug/354985>. Don't let this
+ slow you down too much.)
+
#. Summarize into one or two paragraphs what's new in this release.
#. Commit these changes to the release branch, using a command like::
@@ -218,6 +238,28 @@
at any time.
+Starting a cycle
+----------------
+
+To start a new release cycle:
+
+#. Send mail to the list with the key dates, who will be the release
+ manager, and the main themes or targeted bugs. Ask people to nominate
+ objectives, or point out any high-risk things that are best done early,
+ or that interact with other changes.
+
+#. Add a new "series" in Launchpad at <https://launchpad.net/bzr/+addseries>.
+ There is one series for every *x.y* release.
+
+#. Add milestones to that series for the release candidate and the final
+ release, and their expected dates.
+
+#. Deactivate old releases and their milestones.
+
+#. Update the version number in the ``bzr`` script, and the
+ ``bzrlib/__init__.py`` file.
+
+
See also
--------
=== modified file 'doc/index.txt'
--- a/doc/index.txt 2009-07-22 14:07:56 +0000
+++ b/doc/index.txt 2009-08-10 06:53:44 +0000
@@ -21,9 +21,6 @@
* `2.0 Upgrade Guide <en/upgrade-guide/index.html>`_
-* `Developer Document Catalog <developers/index.html>`_ |--| for developers
- of Bazaar and plugins
-
Tutorials
=========
@@ -37,6 +34,12 @@
* `Centralized workflow <en/tutorials/centralized_workflow.html>`_
+Developer Documentation
+=======================
+
+* `Developer Document Catalog <developers/index.html>`_ |--| for developers
+ of Bazaar and plugins
+
Web links
=========
More information about the bazaar-commits
mailing list