1
The Bazaar Development Cycle
2
============================
9
We normally have one person acting as the release manager, who
10
organizes development for the release and also actually makes the release
11
tarball and posts announcements. It can be a different person from one
14
Our usual process is that one week before release we will make a release
15
branch from the trunk. We do one commit to that branch to change the
16
version number to 'rc1', and advance the trunk version to 'dev' for the
19
We then publish and announce this release candidate according to the
20
process below. We then have a week of general testing of the rc,
21
including some time for plugin authors to update their code for any
24
Normally no changes will be made on the release branch unless serious bugs
25
or regressions are found, and the release manager decides they should be
26
merged in. After one week, the release branch's version number is updated
27
and it's published as the final release. If regressions or serious
28
problems are discovered after the final release we may make an additional
29
point release from that branch.
31
The process or timing can vary if that seems appropriate in a particular
32
case but we try to release on a regular four week cycle.
34
The net effect is that the code gets some extra testing before release,
35
and the trunk is always open for general development.
41
To start a new release cycle:
43
#. Send mail to the list with the key dates, who will be the release
44
manager, and the main themes or targetted bugs. Ask people to nominate
45
objectives, or point out any high-risk things that are best done early,
46
or that interact with other changes.
48
#. Add a new "series" in Launchpad at <https://launchpad.net/bzr/+addseries>.
49
There is one series for every *x.y* release.
51
#. Add milestones to that series for the release candidate and the final
52
release, and their expected dates.
54
#. Deactivate old releases and their milestones.
56
#. Update the version number in the ``bzr`` script, and the
57
``bzrlib/__init__.py`` file.
5
:status: Current policy, as of 2010-10.
6
:blueprint: <https://blueprints.launchpad.net/bzr/+spec/6m-cycle>
9
Our users want easy access to bug fixes without other changes to the
10
core product. They also want a Just Works experience across the full
11
Bazaar ecosystem. To deliver the first and enable the second, we're
12
adopting some standard process patterns: a 6 monthly release cycle and a
13
stable series. These changes will also have other benefits, including
14
better availability of bug fixes in OS distributions, more freedom to
15
remove old code, and less work for in packaging.
19
* `Bazaar Developer Document Catalog <index.html>`_
21
* `Releasing Bazaar <releasing.html>`_ -- the process for actually making
22
a release or release candidate.
28
Bazaar will make a major release every six months, which will be supported at
29
least until the time of the next major release and generally 18 months after
30
the first final release in a series. During this support period, we'll make
31
incremental releases which fix bugs, but which do not change network or disk
32
formats or command syntax, and which do not require updates to plugins.
34
We will also run a development series, which will become the next major
35
release. We'll make a beta release from this every four weeks. The
36
beta releases will be as stable as our current monthly releases and
37
completely suitable for everyday use by users who can tolerate changes
40
Having the stable series isn't a reason to cut back on QA or to make the
41
trunk or development releases unstable, which would only make our job
42
harder. We keep our trunk in an always-releasable state, and that should
43
continue: any beta release could potentially be supported in the long
44
term, but we identify particular releases that actually will be supported.
46
The trunk will never be frozen: changes that pass review, other quality
47
checks and that are agreed amongst the developers can always be landed
48
into trunk. The only restrictions will be on branches specifically
49
targeted at a release.
57
2.0.0 --- 2.0.1 -- 2.0.2 -- ...
59
+--2.1.0beta1 -- 2.1.0beta2 -- ... -- 2.1.0rc1 -- 2.1.0 -- 2.1.1 -- ...
65
Starting from the date of a major release:
67
At four-week intervals we make a new beta release. There will be no
68
separate release candidate, but if a serious problem is discovered we may
69
do the next beta ahead of schedule or make a point release. There will be
70
about five or six releases in that series.
72
In parallel with this, bugs targeted to the previous major release are
73
merged into its branch. We will make bugfix releases from that branch as
74
appropriate to the accumulation of changes, perhaps monthly, perhaps more
75
often if there are serious bugs, perhaps much less often if no new changes
78
We will synchronize our major releases with Ubuntu, so that they come out
79
in sufficient time for some testing and margin of error before Ubuntu's
86
We value regular releases. We prefer to slip a feature or fix to
87
a later release rather than to make a release late. We will normally only
88
slip a release to fix a critical bug.
94
The number for a six-month cycle is chosen at the start, with an increment
95
to either the first field (3.0.0) or second field (3.1.0) depending on
96
what we expect to be the user impact of the release. We expect releases
97
that culminate in a new disk format or that require changes in how people
98
use the tool will get a new major number. We can change (forward only) if
99
it turns out that we land larger changes than were expected.
101
We will always use the 3-digit form (major.minor.micro) even when
102
referring to the initial major release. This should help clarify where a
103
patch is intended to land. (eg, "I propose this for 2.0.0" is clear, while
104
"I propose this for 2.0" could mean you want to make the 2.0.0 release, or
105
that you just want to land on the 2.0.x stable release series.)
111
Major releases (2.0.0 or 2.1.0)
113
The big ones, every six months, intended to ship in distributions and
114
to be used by stability-oriented users.
116
Release candidate (2.0.0rc1)
118
A preview of a major release, made one or a few weeks beforehand at the
119
time the release branch is created. There should be few if any changes
120
from the rc to the stable release. We should avoid the confusing phrasing
121
"release candidate 2.0.0rc1 is released"; instead use "available."
122
Starting with the 2.3 series we don't plan on making release candidates
125
Bugfix releases (2.0.1)
127
Based on the previous major release or bugfix; contains only bugfixes
128
and perhaps documentation or translation corrections.
132
A major release and its descendant bugfix releases.
136
Either a major release or a bugfix release.
138
Beta release (3.0.0beta1)
140
Made from trunk every month, except for the month there's a major
141
release. Stable and suitable for users who want the latest code and
142
can live with some changes from month to month.
146
The development releases leading up to a stable release.
151
Bug fixes should normally be done first against the stable branch,
152
reviewed against that branch, and then merged forward to trunk.
154
It may not always be easy to do this, if fixing the bug requires large
155
changes or the affected code is different in the stable and development
156
branches. If the tradeoff does not seem worthwhile the bug can be fixed
157
only in the development branch, at least in the first instance. If users
158
later want the fix backported we can discuss it.
160
Developers can merge the release branch into trunk as often as they like,
161
only asking for review if they're making nontrivial changes or feel review
165
Feature and Performance Work
166
----------------------------
168
Features can be landed to the development branch at any time, and they'll
169
be released for testing within a month.
171
Performance bugs, although important, will generally not be landed in a
172
stable series. Fixing performance bugs well often requires nontrivial
173
code changes or new formats. These are not suitable for a stable series.
175
Performance bugs that can be fixed with a small safe patch can be
176
considered for the stable series.
182
Plugins that want to cooperate with this should make a series and a branch
183
that matches each bzr stable series, and follow similar rules in making
184
releases from their stable branch. We'd expect that plugins will make a
185
release between the first beta release of a series and the final major
188
Within a stable series, anything that breaks any known plugin is
189
considered an API break and will be avoided. Before
190
making each bugfix release, we'll test that code against important
193
Within a development series, the focus is on helping plugin authors keep
194
up to date by giving clear error messages when an interface is removed.
195
We will no longer focus on letting old plugin code work with new versions
196
of bzrlib, which is an elusive target in Python.
198
This may mean that in cases where today a plugin would keep running but
199
give warnings, it will now fail altogether with an error.
201
In return we expect more freedom to change and cleanup bzrlib code without
202
needing to keep old code around, or write extra compatibility shims, or
203
have review turnarounds related to compatibility. Some changes, such as
204
removing module-global variables, that are hard to do now, will be
205
possible to do safely.
207
Discussion of plugins here includes programs that import and use bzrlib
208
but that aren't technically plugins. The same approach, though the
209
technical considerations are different, should apply to other extensions
210
such as programs that use bzr through the shell interface.
214
Data and Network Formats
215
------------------------
217
Any development release should be able to interoperate with the previous
218
stable release, and any stable release should be able to interoperate with
219
the previous stable release. This is a minimum and normally releases will be
220
able to interoperate with all previous releases as at present.
222
Each major release will have one recommended data format which will be the
223
default. The name of the format will indicate which release series (not
224
specific release) it comes from: '2a' is the first supported format for
225
the 2.0.x series, '2b' the second, etc. We don't mention the particular
226
release that introduced it so as to avoid problems predicting precisely
229
During a development series we may have a series of experimental formats.
230
We will not leave people stranded if they test these formats, but we also
231
won't guarantee to keep supporting them in a future release. If something
232
inserted in one development release turns out to be bad it can just be
239
The guarantees made above about format and network interoperation
240
mean that hosting services such as Launchpad, Savannah, FedoraHosted,
241
and Sourceforge could choose to run either the stable or beta versions.
242
They might find it useful to run the beta version on their own beta
246
Simultaneous Installation
247
-------------------------
249
Some people may want to simultaneously install and use both a stable
250
release and development release.
252
This can be handled in various ways either at the OS packaging or the
253
Python level. We don't propose to directly address it in the upstream
254
source. (For example, we will not change the bzrlib library name from one
255
release to the next.)
257
The issue already exists with people who may want to use for example the
258
previous bzr release and the trunk. There is a related issue that plugins
259
may be compatible with only some of the Bazaar versions people want to use
260
at the same time, and again that is something that can be handled
267
OS distributors will be recommended to ship the bzr stable release that
268
fits their schedule, the betas leading up to that release during their own
269
beta period, and the bugfix releases following on from it. They might
270
also choose to offer the beta releases as an alternative package.
276
At present we have three upstream-maintained PPAs containing Ubuntu packages
277
of Bazaar: ``bzr/daily`` (snapshots), ``bzr-beta-ppa/ppa`` (beta releases) and
278
``bzr/ppa`` (ie stable). Beta contains the monthly beta releases, and the
279
stable PPA contains stable releases and bugfixes to those releases.
281
Some platforms with relatively less active packagers may choose to ship
282
only the stable releases. This is probably better than having them only
283
intermittently or slowly ship the monthly releases.
285
Binary installers should use a version number like '2.0.0-1' or
286
'2.0.0beta1-1' so that the last component just reflects the packaging
287
version, and can be incremented if a new installer is made with no
288
upstream source changes.
291
Code Freeze vs Announcement
292
---------------------------
294
We will separate the code freeze for a particular release from its actual
295
announcement, allowing a window of approximately one week for plugins to
296
be released and binary installers to be built. On the date the
297
announcement is published, people will be able to easily install it.
60
300
Weekly Metronome Mail
76
316
of certain things, etc.
79
Starting the release phase
80
--------------------------
82
When it's time to make the release candidate:
84
#. We create a new pqm-controlled branch for this release series. The
85
branch must be created by Robert Collins on the pqm server.
86
This branch means that from the first release candidate onwards,
87
general development continues on the trunk, and only
88
specifically-targetted fixes go into the release.
90
#. Register the branch at <https://launchpad.net/products/bzr/+addbranch>
92
#. The revision at the start of that branch is `released
93
<releasing.html>`_ as the first RC.
99
* `Bazaar Developer Document Catalog <index.html>`_
101
* `Releasing Bazaar <releasing.html>`_ -- the process for actually making
102
a release or release candidate.
322
Do users actually want this?
323
Apparently yes, because it's often requested and often raised as a
326
Would this confuse users?
327
It shouldn't, because it's a fairly standard scheme.
329
Won't it take more time to fix bugs in multiple places?
330
It shouldn't, because we'll only do this when the stable bugfix seems
331
economical. When we fix bugs today in both trunk and release branches
332
it normally does not take much more time.
334
What about bzr in Ubuntu LTS, with a five-year support life?
335
Most bugs are either fixed within six months, or not fixed at all, or
336
not very important, or fixed as part of a large rework of the code
337
that would be too large to backport. However, if there are fixes that
338
are especially desired in an old release and feasible to do, we can do
339
them without making a general commitment.
341
Will anyone test the beta releases?
342
Probably yes, our most active users will run them, but if people would
343
really rather not test them, forcing them is not helpful.
345
Isn't this a step backwards to a slower, less-agile process?
346
No, our trunk stays releasable, and we ship every month. We're just
347
cutting out things that hold us back (continuous rather than episodic
348
API stability; RCs every month) and giving users what they demand.
350
How about calling the monthly releases "milestone" or "next" not "beta"?
351
Those words are less scary but they also have less clear meanings.
357
If this plan works, we'll expect to see the following changes. If they
358
don't occur, we'll think again:
360
* We see a distribution curve of users and bug reports across nightly, monthly
361
and stable releases, indicating that each has value.
363
* API changes are easier or safer to make during beta periods, without
364
being held back by fears of compatibility or
366
* The stable releases are actually stable and don't introduce regressions
369
* Many bugs are fixed in stable branches, without developers feeling this
372
* Distributions ship the stable releases in their stable releases and the
373
bugfix releases in their bugfix releases.
375
* Plugin authors follow this policy, making their own bugfix releases.
379
After doing this for the 2.0 cycle (September 2009 through to early
380
2010), it seems to be going well.
383
Reviewing for the Stable Branch
384
*******************************
386
These are guidelines and can be interpreted case-by-case.
388
* All changes to the stable branch should fix a bug, even if you would not
389
normally file a bug for the change. The bug description should if at
390
all possible explain how to manually verify the bug in a way that will
391
fail before and pass after the change. (These are requirements for the
394
* The change should be reasonably small and conservative.
396
* Remember that the patch will be read during the SRU
397
process and so keeping the patch small is useful even beyond keeping the
398
logical changes small. Avoid doing mechanical bulk changes on the
401
* Use particular care for things that may behave differently across
402
platforms, encodings or locales. It's harder to thoroughly test these
403
things before a release.
405
* Generally speaking, just cleaning things up is not a sufficient reason
406
to make changes to the stable branch. It has to actually fix a bug.
408
* Changes to the stable branch should include tests as usual.
410
* Don't change or remove existing APIs that might be used by plugins, even
411
if they are underscore-prefixed. Adding APIs that are also being added
412
to the trunk branch may make sense.
414
* Keeping consistency with trunk is useful, but less important than
415
keeping the stable branch stable.
417
* (more items welcome)
422
#. List thread "`[rfc] six-month stable release cycles`__", July 2009.
424
.. __: https://lists.ubuntu.com/archives/bazaar/2009q3/060882.html
106
427
vim: filetype=rst textwidth=74 ai shiftwidth=4
added
removed
doc/developers/cycle.txt
