~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/cycle.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-02-01 13:53:24 UTC
  • mfrom: (4990.1.2 rm-obsolete)
  • Revision ID: pqm@pqm.ubuntu.com-20100201135324-cuhuolr97guf5xjp
(Jelmer) Remove obsolete (and broken) biobench and history2revfiles
        tools.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
*********************
 
2
Bazaar Release Cycles
 
3
*********************
 
4
 
 
5
:status: Current policy, as of 2009-08.
 
6
:blueprint: <https://blueprints.launchpad.net/bzr/+spec/6m-cycle>
 
7
 
 
8
 
 
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 branch. 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.
 
16
 
 
17
See also:
 
18
 
 
19
* `Bazaar Developer Document Catalog <index.html>`_
 
20
 
 
21
* `Releasing Bazaar <releasing.html>`_ -- the process for actually making
 
22
  a release or release candidate.
 
23
 
 
24
 
 
25
The Process
 
26
************
 
27
 
 
28
Bazaar will make a major release every six months, which will be supported
 
29
at least until the time of the next major release.  During this support
 
30
period, we'll make incremental releases which fix bugs, but which do not
 
31
change network or disk formats or command syntax, and which do not require
 
32
updates to plugins.
 
33
 
 
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
 
38
from month to month.
 
39
 
 
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.
 
45
 
 
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.
 
50
 
 
51
 
 
52
Schedule
 
53
--------
 
54
 
 
55
::
 
56
 
 
57
 2.0.0 --- 2.0.1 -- 2.0.2 -- ...
 
58
  \
 
59
   +--2.1.0beta1 -- 2.1.0beta2 -- ... -- 2.1.0rc1 -- 2.1.0 -- 2.1.1 -- ...
 
60
                                                      \
 
61
                                                       \
 
62
                                                        +-- 3.0.0beta1 ...
 
63
 
 
64
 
 
65
Starting from the date of a major release:
 
66
 
 
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.
 
71
 
 
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
 
76
have landed.
 
77
 
 
78
We will then make a release candidate for the next major release, and at
 
79
this point create a release branch for it.  We will iterate release
 
80
candidates at approximately weekly intervals until there are no bugs
 
81
blocking the final major release.
 
82
 
 
83
Compared to the current process this has approximately the same amount of
 
84
release-related work, because the extra releases from the stable branch
 
85
are "paid for" by not doing RCs for the development series.
 
86
 
 
87
We will synchronize our major releases with Ubuntu, so that they come out
 
88
in sufficient time for some testing and margin of error before Ubuntu's
 
89
upstream freeze.
 
90
 
 
91
 
 
92
Regularity
 
93
----------
 
94
 
 
95
We value regular releases.  We prefer to slip a feature or fix to
 
96
a later release rather than to make a release late.  We will normally only
 
97
slip a release to fix a critical bug.
 
98
 
 
99
 
 
100
Numbering
 
101
---------
 
102
 
 
103
The number for a six-month cycle is chosen at the start, with an increment
 
104
to either the first field (3.0.0) or second field (3.1.0) depending on
 
105
what we expect to be the user impact of the release.  We expect releases
 
106
that culminate in a new disk format or that require changes in how people
 
107
use the tool will get a new major number.  We can change (forward only) if
 
108
it turns out that we land larger changes than were expected.
 
109
 
 
110
We will always use the 3-digit form (major.minor.micro) even when
 
111
referring to the initial major release. This should help clarify where a
 
112
patch is intended to land. (eg, "I propose this for 2.0.0" is clear, while
 
113
"I propose this for 2.0" could mean you want to make the 2.0.0 release, or
 
114
that you just want to land on the 2.0.x stable release series.)
 
115
 
 
116
 
 
117
Terminology
 
118
-----------
 
119
 
 
120
Major releases (2.0.0 or 2.1.0)
 
121
    The big ones, every six months, intended to ship in distributions and
 
122
    to be used by stability-oriented users.
 
123
 
 
124
Release candidate (2.0.0rc1)
 
125
    A preview of a major release, made one or a few weeks beforehand at
 
126
    the time the release branch is created.  There should be few if any
 
127
    changes from the rc to the stable release.  We should avoid the
 
128
    confusing phrasing "release candidate 2.0.0rc1 is released"; instead
 
129
    use "available."
 
130
 
 
131
Bugfix releases (2.0.1)
 
132
    Based on the previous major release or bugfix; contains only bugfixes
 
133
    and perhaps documentation or translation corrections.
 
134
 
 
135
Stable series
 
136
    A major release and its descendant bugfix releases.
 
137
 
 
138
Stable release
 
139
    Either a major release or a bugfix release.
 
140
 
 
141
Beta release (3.0.0beta1)
 
142
    Made from trunk every month, except for the month there's a major
 
143
    release.  Stable and suitable for users who want the latest code and
 
144
    can live with some changes from month to month.
 
145
 
 
146
Development series
 
147
    The development releases leading up to a stable release.
 
148
 
 
149
Bug Work
 
150
--------
 
151
 
 
152
Bug fixes should normally be done first against the stable branch,
 
153
reviewed against that branch, and then merged forward to trunk.
 
154
 
 
155
It may not always be easy to do this, if fixing the bug requires large
 
156
changes or the affected code is different in the stable and development
 
157
branches.  If the tradeoff does not seem worthwhile the bug can be fixed
 
158
only in the development branch, at least in the first instance.  If users
 
159
later want the fix backported we can discuss it.
 
160
 
 
161
Developers can merge the release branch into trunk as often as they like,
 
162
only asking for review if they're making nontrivial changes or feel review
 
163
is needed.
 
164
 
 
165
 
 
166
Feature and Performance Work
 
167
----------------------------
 
168
 
 
169
Features can be landed to the development branch at any time, and they'll
 
170
be released for testing within a month.
 
171
 
 
172
Performance bugs, although important, will generally not be landed in a
 
173
stable series.  Fixing performance bugs well often requires nontrivial
 
174
code changes or new formats.  These are not suitable for a stable series.
 
175
 
 
176
Performance bugs that can be fixed with a small safe patch can be
 
177
considered for the stable series.
 
178
 
 
179
 
 
180
Plugins
 
181
-------
 
182
 
 
183
Plugins that want to cooperate with this should make a series and a branch
 
184
that matches each bzr stable series, and follow similar rules in making
 
185
releases from their stable branch.  We'd expect that plugins will make a
 
186
release between the last development release of a series and the major
 
187
release candidate.
 
188
 
 
189
Within a stable series, anything that breaks any known plugin is
 
190
considered an API break and will be avoided.  Before
 
191
making each bugfix release, we'll test that code against important
 
192
plugins.
 
193
 
 
194
Within a development series, the focus is on helping plugin authors keep
 
195
up to date by giving clear error messages when an interface is removed.
 
196
We will no longer focus on letting old plugin code work with new versions
 
197
of bzrlib, which is an elusive target in Python.
 
198
 
 
199
This may mean that in cases where today a plugin would keep running but
 
200
give warnings, it will now fail altogether with an error.
 
201
 
 
202
In return we expect more freedom to change and cleanup bzrlib code without
 
203
needing to keep old code around, or write extra compatibility shims, or
 
204
have review turnarounds related to compatibility.  Some changes, such as
 
205
removing module-global variables, that are hard to do now, will be
 
206
possible to do safely.
 
207
 
 
208
Discussion of plugins here includes programs that import and use bzrlib
 
209
but that aren't technically plugins.  The same approach, though the
 
210
technical considerations are different, should apply to other extensions
 
211
such as programs that use bzr through the shell interface.
 
212
 
 
213
 
 
214
 
 
215
Data and Network Formats
 
216
------------------------
 
217
 
 
218
Any development release should be able to interoperate with the previous
 
219
stable release, and any stable release should be able to interoperate with
 
220
the previous stable release.  This is a minimum and normally releases will be
 
221
able to interoperate with all previous releases as at present.
 
222
 
 
223
Each major release will have one recommended data format which will be the
 
224
default.  The name of the format will indicate which release series (not
 
225
specific release) it comes from: '2a' is the first supported format for
 
226
the 2.0.x series, '2b' the second, etc.  We don't mention the particular
 
227
release that introduced it so as to avoid problems predicting precisely
 
228
when it will land.
 
229
 
 
230
During a development series we may have a series of experimental formats.
 
231
We will not leave people stranded if they test these formats, but we also
 
232
won't guarantee to keep supporting them in a future release.  If something
 
233
inserted in one development release turns out to be bad it can just be
 
234
removed in the next.
 
235
 
 
236
 
 
237
Hosting Services
 
238
-----------------
 
239
 
 
240
The guarantees made above about format and network interoperation
 
241
mean that hosting services such as Launchpad, Savannah, FedoraHosted,
 
242
and Sourceforge could choose to run either the stable or beta versions.
 
243
They might find it useful to run the beta version on their own beta
 
244
server.
 
245
 
 
246
 
 
247
Simultaneous Installation
 
248
-------------------------
 
249
 
 
250
Some people may want to simultaneously install and use both a stable
 
251
release and development release.
 
252
 
 
253
This can be handled in various ways either at the OS packaging or the
 
254
Python level.  We don't propose to directly address it in the upstream
 
255
source.  (For example, we will not change the bzrlib library name from one
 
256
release to the next.)
 
257
 
 
258
The issue already exists with people who may want to use for example the
 
259
previous bzr release and the trunk.  There is a related issue that plugins
 
260
may be compatible with only some of the Bazaar versions people want to use
 
261
at the same time, and again that is something that can be handled
 
262
separately.
 
263
 
 
264
 
 
265
OS Distributions
 
266
----------------
 
267
 
 
268
OS distributors will be recommended to ship the bzr stable release that
 
269
fits their schedule, the betas leading up to that release during their own
 
270
beta period, and the bugfix releases following on from it.  They might
 
271
also choose to offer the beta releases as an alternative package.
 
272
 
 
273
 
 
274
Packaging
 
275
---------
 
276
 
 
277
At present we have three upstream-maintained PPAs containing Ubuntu
 
278
packages of Bazaar: ``~bzr-nightly-ppa``, ``~bzr-beta-ppa`` (rcs and
 
279
releases) and ``~bzr`` (ie stable).  We will keep these PPAs, and reorient
 
280
beta to contain the monthly beta releases, and the stable PPA to contain
 
281
stable releases, their release candidates, and bugfixes to those releases.
 
282
 
 
283
Some platforms with relatively less active packagers may choose to ship
 
284
only the stable releases.  This is probably better than having them only
 
285
intermittently or slowly ship the monthly releases.
 
286
 
 
287
Binary installers should use a version number like '2.0.0-1' or
 
288
'2.0.0beta1-1' so that the last component just reflects the packaging
 
289
version, and can be incremented if a new installer is made with no
 
290
upstream source changes.
 
291
 
 
292
 
 
293
Code Freeze vs Announcement
 
294
---------------------------
 
295
 
 
296
We will separate the code freeze for a particular release from its actual
 
297
announcement, allowing a window of approximately one week for plugins to
 
298
be released and binary installers to be built.  On the date the
 
299
announcement is published, people will be able to easily install it.
 
300
 
 
301
 
 
302
Weekly Metronome Mail
 
303
---------------------
 
304
 
 
305
Every week the release manager should send a mail to the Bazaar list
 
306
covering these points (as appropriate):
 
307
 
 
308
* Early communication about changing dependencies or defaults
 
309
 
 
310
* Reminder re lifecycle and where we're up to right now, in particular the
 
311
  dates for the next release and/or candidate.
 
312
 
 
313
* Summary of recent successes and pending work.
 
314
 
 
315
* Reminder re release objectives
 
316
 
 
317
* Reminder re things needing attention, e.g. bug triage, reviews, testing
 
318
  of certain things, etc.
 
319
 
 
320
 
 
321
Questions
 
322
*********
 
323
 
 
324
Do users actually want this?
 
325
    Apparently yes, because it's often requested and often raised as a
 
326
    problem.
 
327
 
 
328
Would this confuse users?
 
329
    It shouldn't, because it's a fairly standard scheme.
 
330
 
 
331
Won't it take more time to fix bugs in multiple places?
 
332
    It shouldn't, because we'll only do this when the stable bugfix seems
 
333
    economical.  When we fix bugs today in both trunk and release branches
 
334
    it normally does not take much more time.
 
335
 
 
336
What about bzr in Ubuntu LTS, with a five-year support life?
 
337
    Most bugs are either fixed within six months, or not fixed at all, or
 
338
    not very important, or fixed as part of a large rework of the code
 
339
    that would be too large to backport.  However, if there are fixes that
 
340
    are especially desired in an old release and feasible to do, we can do
 
341
    them without making a general commitment.
 
342
 
 
343
Will anyone test the beta releases?
 
344
    Probably yes, our most active users will run them, but if people would
 
345
    really rather not test them, forcing them is not helpful.
 
346
 
 
347
Isn't this a step backwards to a slower, less-agile process?
 
348
    No, our trunk stays releasable, and we ship every month.  We're just
 
349
    cutting out things that hold us back (continuous rather than episodic
 
350
    API stability; RCs every month) and giving users what they demand.
 
351
 
 
352
How about calling the monthly releases "milestone" or "next" not "beta"?
 
353
    Those words are less scary but they also have less clear meanings.
 
354
 
 
355
 
 
356
Expected Benefits
 
357
*****************
 
358
 
 
359
If this plan works, we'll expect to see the following changes.  If they
 
360
don't occur, we'll think again:
 
361
 
 
362
* We see a distribution curve of users and bug reports across nightly, monthly
 
363
  and stable releases, indicating that each has value.
 
364
 
 
365
* API changes are easier or safer to make during beta periods, without
 
366
  being held back by fears of compatibility or
 
367
 
 
368
* The stable releases are actually stable and don't introduce regressions
 
369
  or break plugins.
 
370
 
 
371
* Many bugs are fixed in stable branches, without developers feeling this
 
372
  is a waste of time.
 
373
 
 
374
* Distributions ship the stable releases in their stable releases and the
 
375
  bugfix releases in their bugfix releases.
 
376
 
 
377
* Plugin authors follow this policy, making their own bugfix releases.
 
378
 
 
379
* Users like it.
 
380
 
 
381
After doing this for the 2.0 cycle (September 2009 through to early
 
382
2010), it seems to be going well.
 
383
 
 
384
 
 
385
Reviewing for the Stable Branch
 
386
*******************************
 
387
 
 
388
These are guidelines and can be interpreted case-by-case.
 
389
 
 
390
* All changes to the stable branch should fix a bug, even if you would not
 
391
  normally file a bug for the change.  The bug description should if at
 
392
  all possible explain how to manually verify the bug in a way that will
 
393
  fail before and pass after the change.  (These are requirements for the
 
394
  SRU process.)
 
395
 
 
396
* The change should be reasonably small and conservative.  
 
397
 
 
398
* Remember that the patch will be read during the SRU
 
399
  process and so keeping the patch small is useful even beyond keeping the
 
400
  logical changes small.  Avoid doing mechanical bulk changes on the
 
401
  stable branch.
 
402
 
 
403
* Use particular care for things that may behave differently across
 
404
  platforms, encodings or locales.  It's harder to thoroughly test these
 
405
  things before a release.
 
406
 
 
407
* Generally speaking, just cleaning things up is not a sufficient reason
 
408
  to make changes to the stable branch.  It has to actually fix a bug.
 
409
 
 
410
* Changes to the stable branch should include tests as usual.  
 
411
 
 
412
* Don't change or remove existing APIs that might be used by plugins, even
 
413
  if they are underscore-prefixed.  Adding APIs that are also being added
 
414
  to the trunk branch may make sense.
 
415
 
 
416
* Keeping consistency with trunk is useful, but less important than
 
417
  keeping the stable branch stable.
 
418
 
 
419
* (more items welcome)
 
420
 
 
421
References
 
422
**********
 
423
 
 
424
#. List thread "`[rfc] six-month stable release cycles`__", July 2009.
 
425
 
 
426
.. __: https://lists.ubuntu.com/archives/bazaar/2009q3/060882.html
 
427
 
 
428
..
 
429
   vim: filetype=rst textwidth=74 ai shiftwidth=4