19
21
* `Releasing Bazaar <releasing.html>`_ -- the process for actually making
20
22
a release or release candidate.
25
Work spanning multiple releases is typically tracked in the bug tracker,
26
and summarized in <http://bazaar-vcs.org/Roadmap>.
32
We normally have one person acting as the release manager, who
33
organizes development for the release and also actually makes the release
34
tarball and posts announcements. It can be a different person from one
37
Our usual process is that one week before release we will make a release
38
branch from the trunk. We do one commit to that branch to change the
39
version number to 'rc1', and advance the trunk version to 'dev' for the
42
We then publish and announce this release candidate according to the
43
process below. We then have a week of general testing of the rc,
44
including some time for plugin authors to update their code for any
47
Normally no changes will be made on the release branch unless serious bugs
48
or regressions are found, and the release manager decides they should be
49
merged in. After one week, the release branch's version number is updated
50
and it's published as the final release. If regressions or serious
51
problems are discovered after the final release we may make an additional
52
point release from that branch.
54
The process or timing can vary if that seems appropriate in a particular
55
case but we try to release on a regular four week cycle.
57
The net effect is that the code gets some extra testing before release,
58
and the trunk is always open for general development.
64
To start a new release cycle:
66
#. Send mail to the list with the key dates, who will be the release
67
manager, and the main themes or targetted bugs. Ask people to nominate
68
objectives, or point out any high-risk things that are best done early,
69
or that interact with other changes.
71
#. Add a new "series" in Launchpad at <https://launchpad.net/bzr/+addseries>.
72
There is one series for every *x.y* release.
74
#. Add milestones to that series for the release candidate and the final
75
release, and their expected dates.
77
#. Deactivate old releases and their milestones.
79
#. Update the version number in the ``bzr`` script, and the
80
``bzrlib/__init__.py`` file.
27
Bazaar makes a release every month, preceded by a one-week
28
release-candidate test.
30
In any release we may fix bugs, add formats, change the default format,
31
improve performance, add new commands or change command line behaviour,
32
change the network protocol, or deprecate APIs. We sometimes also
33
introduce new bugs, regress existing behaviour or performance, remove
34
existing features or formats, or break behaviour or APIs depended upon by
35
plugins, external programs or users.
37
Some users are happy upgrading every month and consider the overall
38
positive balance of changes is worth some amount of churn. But there are
39
some serious problems:
41
* You cannot get bug fixes without also getting disruptive changes.
43
* Bazaar is seen as unstable.
45
* Many releases cause some plugin breakage.
47
* One month is not a very long window for dependent programs or systems
48
to catch up to changes in Bazaar before the release goes out of date.
50
* There's no clear indication to distributions which version they should
53
* If people (or their distributions) just pick an arbitrary version, they
54
may all be on different arbitrary versions, therefore they will have
55
different behaviour and different bugs, and sometimes interoperation
58
* Any effort we, or distributors, wanted to put into backporting fixes
59
would be dissipated across many possible backport target releases.
61
* When in the past we've tried either stalling releases for particular
62
features, or having trunk frozen for some weeks, it causes churn and
63
waste. People rush features in, or already landed features wait a long
64
time to be released, or branches go out of date because they cannot
71
Bazaar will make a major release every six months, which will be supported
72
at least until the time of the next major release. During this support
73
period, we'll make incremental releases which fix bugs, but which do not
74
change network or disk formats or command syntax, and which do not require
77
We will also run a development series, which will become the next major
78
release. We'll make a beta release from this every four weeks. The
79
beta releases will be as stable as our current monthly releases and
80
completely suitable for everyday use by users who can tolerate changes
83
Having the stable series isn't a reason to cut back on QA or to make the
84
trunk or development releases unstable, which would only make our job
85
harder. We keep our trunk in an always-releasable state, and that should
86
continue: any beta release could potentially be supported in the long
87
term, but we identify particular releases that actually will be supported.
89
The trunk will never be frozen: changes that pass review, other quality
90
checks and that are agreed amongst the developers can always be landed
91
into trunk. The only restrictions will be on branches specifically
92
targeted at a release.
100
2.0 --- 2.0.1 -- 2.0.2 -- ...
102
+--2.1beta1 -- 2.1beta2 -- ... -- 2.1rc1 -- 2.1 -- 2.1.1 -- ...
108
Starting from the date of a major release:
110
At four-week intervals we make a new beta release. There will be no
111
separate release candidate, but if a serious problem is discovered we may
112
do the next beta ahead of schedule or make a point release. There will be
113
about five or six releases in that series.
115
In parallel with this, bugs targeted to the previous major release are
116
merged into its branch. We will make bugfix releases from that branch as
117
appropriate to the accumulation of changes, perhaps monthly, perhaps more
118
often if there are serious bugs, perhaps much less often if no new changes
121
We will then make a release candidate for the next major release, and at
122
this point create a release branch for it. We will iterate release
123
candidates at approximately weekly intervals until there are no bugs
124
blocking the final major release.
126
Compared to the current process this has approximately the same amount of
127
release-related work, because the extra releases from the stable branch
128
are "paid for" by not doing RCs for the development series.
130
We will synchronize our major releases with Ubuntu, so that they come out
131
in sufficient time for some testing and margin of error before Ubuntu's
138
We value regular releases. We prefer to slip a feature or fix to
139
a later release rather than to make a release late. We will normally only
140
slip a release to fix a critical bug.
146
The number for a six-month cycle is chosen at the start, with an increment
147
to either the first field (3.0) or second field (3.1) depending on what we
148
expect to be the user impact of the release. We expect releases that
149
culminate in a new disk format or that require changes in how people use
150
the tool will get a new major number. We can change (forward only) if it
151
turns out that we land larger changes than were expected.
157
Major releases (2.0 or 2.1)
158
The big ones, every six months, intended to ship in distributions and
159
to be used by stability-oriented users.
161
Release candidate (2.0rc1)
162
A preview of a major release, made one or a few weeks beforehand at
163
the time the release branch is created. There should be few if any
164
changes from the rc to the stable release. We should avoid the
165
confusing phrasing "release candidate 2.0rc1 is released"; instead use
168
Bugfix releases (2.0.1)
169
Based on the previous major release or bugfix; contains only bugfixes
170
and perhaps documentation or translation corrections.
173
A major release and its descendant bugfix releases.
176
Either a major release or a bugfix release.
178
Beta release (3.0beta1)
179
Made from trunk every month, except for the month there's a major
180
release. Stable and suitable for users who want the latest code and
181
can live with some changes from month to month.
184
The development releases leading up to a stable release.
189
Bug fixes should normally be done first against the stable branch,
190
reviewed against that branch, and then merged forward to trunk.
192
It may not always be easy to do this, if fixing the bug requires large
193
changes or the affected code is different in the stable and development
194
branches. If the tradeoff does not seem worthwhile the bug can be fixed
195
only in the development branch, at least in the first instance. If users
196
later want the fix backported we can discuss it.
198
Developers can merge the release branch into trunk as often as they like,
199
only asking for review if they're making nontrivial changes or feel review
203
Feature and Performance Work
204
----------------------------
206
Features can be landed to the development branch at any time, and they'll
207
be released for testing within a month.
209
Performance bugs, although important, will generally not be landed in a
210
stable series. Fixing performance bugs well often requires nontrivial
211
code changes or new formats. These are not suitable for a stable series.
213
Performance bugs that can be fixed with a small safe patch can be
214
considered for the stable series.
220
Plugins that want to cooperate with this should make a series and a branch
221
that matches each bzr stable series, and follow similar rules in making
222
releases from their stable branch. We'd expect that plugins will make a
223
release between the last development release of a series and the major
226
Within a stable series, anything that breaks any known plugin is
227
considered an API break and will be avoided. Before
228
making each bugfix release, we'll test that code against important
231
Within a development series, the focus is on helping plugin authors keep
232
up to date by giving clear error messages when an interface is removed.
233
We will no longer focus on letting old plugin code work with new versions
234
of bzrlib, which is an elusive target in Python.
236
This may mean that in cases where today a plugin would keep running but
237
give warnings, it will now fail altogether with an error.
239
In return we expect more freedom to change and cleanup bzrlib code without
240
needing to keep old code around, or write extra compatibility shims, or
241
have review turnarounds related to compatibility. Some changes, such as
242
removing module-global variables, that are hard to do now, will be
243
possible to do safely.
245
Discussion of plugins here includes programs that import and use bzrlib
246
but that aren't technically plugins. The same approach, though the
247
technical considerations are different, should apply to other extensions
248
such as programs that use bzr through the shell interface.
252
Data and Network Formats
253
------------------------
255
Any development release should be able to interoperate with the previous
256
stable release, and any stable release should be able to interoperate with
257
the previous stable release. This is a minimum and normally releases will be
258
able to interoperate with all previous releases as at present.
260
Each major release will have one recommended data format which will be the
261
default. The name of the format will indicate which release series (not
262
specific release) it comes from: '2a' is the first supported format for
263
the 2.0 series, '2b' the second, etc. We don't mention the particular
264
release that introduced it so as to avoid problems predicting precisely
267
During a development series we may have a series of experimental formats.
268
We will not leave people stranded if they test these formats, but we also
269
won't guarantee to keep supporting them in a future release. If something
270
inserted in one development release turns out to be bad it can just be
277
The guarantees made above about format and network interoperation
278
mean that hosting services such as Launchpad, Savannah, FedoraHosted,
279
and Sourceforge could choose to run either the stable or beta versions.
280
They might find it useful to run the beta version on their own beta
284
Simultaneous Installation
285
-------------------------
287
Some people may want to simultaneously install and use both a stable
288
release and development release.
290
This can be handled in various ways either at the OS packaging or the
291
Python level. We don't propose to directly address it in the upstream
292
source. (For example, we will not change the bzrlib library name from one
293
release to the next.)
295
The issue already exists with people who may want to use for example the
296
previous bzr release and the trunk. There is a related issue that plugins
297
may be compatible with only some of the Bazaar versions people want to use
298
at the same time, and again that is something that can be handled
305
OS distributors will be recommended to ship the bzr stable release that
306
fits their schedule, the betas leading up to that release during their own
307
beta period, and the bugfix releases following on from it. They might
308
also choose to offer the beta releases as an alternative package.
314
At present we have three upstream-maintained PPAs containing Ubuntu
315
packages of Bazaar: ``~bzr-nightly-ppa``, ``~bzr-beta-ppa`` (rcs and
316
releases) and ``~bzr`` (ie stable). We will keep these PPAs, and reorient
317
beta to contain the monthly beta releases, and the stable PPA to contain
318
stable releases, their release candidates, and bugfixes to those releases.
320
Some platforms with relatively less active packagers may choose to ship
321
only the stable releases. This is probably better than having them only
322
intermittently or slowly ship the monthly releases.
324
Binary installers should use a version number like '2.0-1' or '2.0beta1-1'
325
so that the last component just reflects the packaging version, and can be
326
incremented if a new installer is made with no upstream source changes.
329
Code Freeze vs Announcement
330
---------------------------
332
We will separate the code freeze for a particular release from its actual
333
announcement, allowing a window of approximately one week for plugins to
334
be released and binary installers to be built. On the date the
335
announcement is published, people will be able to easily install it.
83
338
Weekly Metronome Mail
99
354
of certain things, etc.
102
Starting the release phase
103
--------------------------
105
When it's time to make the release candidate:
107
#. We create a new pqm-controlled branch for this release series. The
108
branch must be created by Robert Collins on the pqm server.
109
This branch means that from the first release candidate onwards,
110
general development continues on the trunk, and only
111
specifically-targetted fixes go into the release.
113
#. Register the branch at <https://launchpad.net/products/bzr/+addbranch>
115
#. The revision at the start of that branch is `released
116
<releasing.html>`_ as the first RC.
360
Do users actually want this?
361
Apparently yes, because it's often requested and often raised as a
364
Would this confuse users?
365
It shouldn't, because it's a fairly standard scheme.
367
Won't it take more time to fix bugs in multiple places?
368
It shouldn't, because we'll only do this when the stable bugfix seems
369
economical. When we fix bugs today in both trunk and release branches
370
it normally does not take much more time.
372
What about bzr in Ubuntu LTS, with a five-year support life?
373
Most bugs are either fixed within six months, or not fixed at all, or
374
not very important, or fixed as part of a large rework of the code
375
that would be too large to backport. However, if there are fixes that
376
are especially desired in an old release and feasible to do, we can do
377
them without making a general commitment.
379
Will anyone test the beta releases?
380
Probably yes, our most active users will run them, but if people would
381
really rather not test them, forcing them is not helpful.
383
Isn't this a step backwards to a slower, less-agile process?
384
No, our trunk stays releasable, and we ship every month. We're just
385
cutting out things that hold us back (continuous rather than episodic
386
API stability; RCs every month) and giving users what they demand.
388
How about calling the monthly releases "milestone" or "next" not "beta"?
389
Those words are less scary but they also have less clear meanings.
395
If this plan works, we'll expect to see the following changes. If they
396
don't occur, we'll think again:
398
* We see a distribution curve of users and bug reports across nightly, monthly
399
and stable releases, indicating that each has value.
401
* API changes are easier or safer to make during beta periods, without
402
being held back by fears of compatibility or
404
* The stable releases are actually stable and don't introduce regressions
407
* Many bugs are fixed in stable branches, without developers feeling this
410
* Distributions ship the stable releases in their stable releases and the
411
bugfix releases in their bugfix releases.
413
* Plugin authors follow this policy, making their own bugfix releases.
420
#. List thread "[rfc] six-month stable release cycles", July 2009.
122
423
vim: filetype=rst textwidth=74 ai shiftwidth=4
added
removed
doc/developers/cycle.txt
