~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/releasing.txt

  • Committer: Martin Pool
  • Date: 2005-09-18 00:42:08 UTC
  • mto: (1185.8.2) (974.1.91)
  • mto: This revision was merged to the branch mainline in revision 1390.
  • Revision ID: mbp@sourcefrog.net-20050918004207-f2ed0d29530ea55b
- add new helper TestBase.run_bzr_captured

  captures and returns stdout and stderr from running a command

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
Releasing Bazaar
2
 
================
3
 
 
4
 
This document describes the processes for making and announcing a Bazaar
5
 
release, and managing the release process.  This is just one phase of the
6
 
`overall development cycle <http://doc.bazaar-vcs.org/developers/cycle.html>`_,
7
 
but it's the most complex part.
8
 
This document gives a checklist you can follow from start to end in one
9
 
go.
10
 
 
11
 
If you're helping the Release Manager (RM) for one reason or another, you
12
 
may notice that he didn't follow that document scrupulously. He may have
13
 
good reasons to do that but he may also have missed some parts.
14
 
 
15
 
Follow the document yourself and don't hesitate to create the missing
16
 
milestones for example (we tend to forget these ones a lot).
17
 
 
18
 
.. contents::
19
 
 
20
 
 
21
 
Preconditions
22
 
-------------
23
 
 
24
 
#. Download the pqm plugin and install it into your ``~/.bazaar/plugins``::
25
 
 
26
 
     bzr branch lp:bzr-pqm ~/.bazaar/plugins/pqm
27
 
 
28
 
 
29
 
Starting a cycle
30
 
----------------
31
 
 
32
 
To start a new release cycle:
33
 
 
34
 
#. Create a new series at <https://launchpad.net/bzr/+addseries>. There is one
35
 
   series for every *x.y* release.
36
 
 
37
 
#. Go to the series web page at <https://launchpad.net/bzr/x.y>
38
 
 
39
 
#. Create a new release at
40
 
   <https://launchpad.net/bzr/x.y/+addrelease> and add
41
 
   information about this release. We will not use it yet, but it
42
 
   will be available for targeting or nominating bugs.
43
 
 
44
 
#. We create a new pqm-controlled branch for this release series, by
45
 
   asking a Canonical sysadmin.
46
 
   This branch means that from the first release beta or candidate onwards,
47
 
   general development continues on the trunk, and only
48
 
   specifically-targeted fixes go into the release branch.
49
 
 
50
 
#. Add milestones at <https://edge.launchpad.net/bzr/x.y/+addmilestone> to
51
 
   that series for the beta release, release candidate and the final release,
52
 
   and their expected dates.
53
 
 
54
 
#. Update the version number in the ``bzr`` script, and the
55
 
   ``bzrlib/__init__.py`` file. Make sure there is always a corresponding
56
 
   milestone when you change that version number.
57
 
 
58
 
#. Send mail to the list with the key dates, who will be the release
59
 
   manager, and the main themes or targeted bugs.  Ask people to nominate
60
 
   objectives, or point out any high-risk things that are best done early,
61
 
   or that interact with other changes. This is called the metronome mail
62
 
   and is described in `Development cycles <cycle.html>`_.
63
 
 
64
 
#. Make a local branch for preparing this release.  (Only for the first
65
 
   release in a series, otherwise you should already have a branch.) ::
66
 
 
67
 
     bzr branch trunk prepare-1.14
68
 
 
69
 
#. Configure pqm-submit for this branch, with a section like this (where
70
 
   x.y is the version to release).
71
 
   ``~/.bazaar/locations.conf``::
72
 
 
73
 
        [/home/mbp/bzr/prepare-x.y]
74
 
        pqm_email = Canonical PQM <pqm@bazaar-vcs.org>
75
 
        submit_branch = http://bazaar.launchpad.net/~bzr-pqm/bzr/x.y
76
 
        parent_branch = http://bazaar.launchpad.net/~bzr-pqm/bzr/x.y
77
 
        public_branch = http://bazaar.example.com/prepare-x.y
78
 
        submit_to = bazaar@lists.canonical.com
79
 
        smtp_server = mail.example.com:25
80
 
 
81
 
    Please see <http://doc.bazaar-vcs.org/developers/HACKING.html#an-overview-of-pqm>
82
 
    for more details on PQM
83
 
 
84
 
#. In the release branch, update  ``version_info`` in ``./bzrlib/__init__.py``.
85
 
   Make sure the corresponding milestone exists.
86
 
   Double check that ./bzr ``_script_version`` matches ``version_info``. Check
87
 
   the output of ``bzr --version``.
88
 
 
89
 
   For beta releases use::
90
 
 
91
 
       version_info = (2, 1, 0, 'beta', 1)
92
 
 
93
 
 
94
 
   For release candidates use::
95
 
 
96
 
       version_info = (2, 0, 1, 'candidate', 1)
97
 
 
98
 
 
99
 
Starting the release phase
100
 
--------------------------
101
 
 
102
 
#. Create a new milestone at <https://launchpad.net/bzr/x.y/+addmilestone>
103
 
   for the beta release or release candidate if you haven't already.
104
 
 
105
 
#. Add the date and release number to ``./NEWS``
106
 
 
107
 
   Depending on whether you're doing a beta or a bugfix release, you'll
108
 
   have to create a NEWS section for your release in the right
109
 
   place. Most of the time, the new section is at the top of the file
110
 
   (look what have been done for the various 2.0x and 2.1.0bx releases).
111
 
   The rule is to keep the sections sorted by date. You'll need to be
112
 
   cautious when merging back to trunk to respect that.
113
 
 
114
 
#. To check that all bugs mentioned in ``./NEWS`` are actually marked as
115
 
   closed in Launchpad, you can run ``tools/check-newsbugs.py``::
116
 
 
117
 
     ./tools/check-newsbugs.py NEWS
118
 
 
119
 
   (But note there can be some false positives, and this script may be
120
 
   flaky <https://bugs.edge.launchpad.net/bzr/+bug/354985>.  Don't let
121
 
   this slow you down too much.)
122
 
 
123
 
#. Summarize into one or two paragraphs what's new in this release.
124
 
 
125
 
#. Commit these changes to the release branch, using a command like::
126
 
 
127
 
     bzr commit -m "Release 1.14."
128
 
 
129
 
   The diff before you commit will be something like::
130
 
 
131
 
     === modified file 'NEWS'
132
 
     --- NEWS        2008-09-17 23:09:18 +0000
133
 
     +++ NEWS        2008-09-23 16:14:54 +0000
134
 
     @@ -4,6 +4,23 @@
135
 
 
136
 
      .. contents::
137
 
 
138
 
     +bzr 1.7 2008-09-23
139
 
     +------------------
140
 
     +
141
 
     +This release includes many bug fixes and a few performance and feature
142
 
     +improvements.  ``bzr rm`` will now scan for missing files and remove them,
143
 
     +like how ``bzr add`` scans for unknown files and adds them. A bit more
144
 
     +polish has been applied to the stacking code. The b-tree indexing code has
145
 
     +been brought in, with an eye on using it in a future repository format.
146
 
     +There are only minor installer changes since bzr-1.7rc2.
147
 
     +
148
 
      bzr 1.7rc2 2008-09-17
149
 
      ---------------------
150
 
 
151
 
 
152
 
     === modified file 'bzrlib/__init__.py'
153
 
     --- bzrlib/__init__.py  2008-09-16 21:39:28 +0000
154
 
     +++ bzrlib/__init__.py  2008-09-23 16:14:54 +0000
155
 
     @@ -41,7 +41,7 @@
156
 
      # Python version 2.0 is (2, 0, 0, 'final', 0)."  Additionally we use a
157
 
      # releaselevel of 'dev' for unreleased under-development code.
158
 
 
159
 
     -version_info = (1, 7, 0, 'candidate', 2)
160
 
     +version_info = (1, 7, 0, 'final', 0)
161
 
 
162
 
 
163
 
      # API compatibility version: bzrlib is currently API compatible with 1.7.
164
 
 
165
 
#. Tag the new release::
166
 
 
167
 
     bzr tag bzr-1.14
168
 
 
169
 
#. Push those changes to a bzr reposistory that is public and accessible on
170
 
   the Internet. PQM will pull from this repository when it attempts to merge
171
 
   your changes. Then submit those changes to PQM for merge into the
172
 
   appropriate release branch::
173
 
 
174
 
     bzr push
175
 
     bzr pqm-submit -m "(mbp) prepare 1.14"
176
 
 
177
 
#. When PQM succeeds, pull down the master release branch.
178
 
 
179
 
 
180
 
Making the source tarball
181
 
-------------------------
182
 
 
183
 
#. Change into the source directory and run ::
184
 
 
185
 
     make dist
186
 
 
187
 
#. Now we'll try expanding this tarball and running the test suite
188
 
   to check for packaging problems::
189
 
 
190
 
     make check-dist-tarball
191
 
 
192
 
   You may encounter failures while running the test suite caused
193
 
   by your locally installed plugins. Use your own judgment to
194
 
   decide if you can release with these failures. When in doubt,
195
 
   disable the faulty plugins one by one until you get no more
196
 
   failures.
197
 
 
198
 
 
199
 
Publishing the source tarball
200
 
-----------------------------
201
 
 
202
 
#. Go to the relevant milestone page in Launchpad.
203
 
 
204
 
#. Within that release, upload the source tarball and the GPG
205
 
   signature.  Or, if you prefer, use the
206
 
   ``tools/packaging/lp-upload-release`` script to do this.
207
 
 
208
 
 
209
 
Announcing the source freeze
210
 
----------------------------
211
 
 
212
 
#. Post to the ``bazaar`` list, saying that the source has been frozen.
213
 
   This is the cue for platform maintainers and plugin authors to update
214
 
   their code.  This is done before the general public announcement of the
215
 
   release.
216
 
 
217
 
 
218
 
Publishing the release
219
 
----------------------
220
 
 
221
 
There is normally a delay of a few days after the source freeze to allow
222
 
for binaries to be built on various platforms.  Once they have been built,
223
 
we have a releasable product.  The next step is to make it generally
224
 
available to the world.
225
 
 
226
 
go to the release
227
 
 
228
 
#. Within that release, upload the source tarball and zipfile and the GPG
229
 
   signature.  Or, if you prefer, use the
230
 
   ``tools/packaging/lp-upload-release`` script to do this.
231
 
 
232
 
#. Link from http://bazaar-vcs.org/SourceDownloads to the tarball and
233
 
   signature.
234
 
 
235
 
#. Announce on the `Bazaar website <http://bazaar-vcs.org/>`_.
236
 
   This page is edited via the lp:bzr-website branch. (Changes
237
 
   pushed to this branch are refreshed by a cron job on escudero.)
238
 
 
239
 
#. Announce on the `Bazaar wiki <http://bazaar-vcs.org/Welcome>`_.
240
 
 
241
 
#. Check that the documentation for this release is available in
242
 
   <http://doc.bazaar-vcs.org>.  It should be automatically build when the
243
 
   branch is created, by a cron script ``update-bzr-docs`` on
244
 
   ``escudero``. As of today (2009-08-27) ``igc`` manually updates the
245
 
   pretty version of it.
246
 
 
247
 
 
248
 
Announcing the release
249
 
----------------------
250
 
 
251
 
Now that the release is publicly available, tell people about it.
252
 
 
253
 
#. Make an announcement mail.
254
 
 
255
 
   For release candidates or beta releases, this is sent to the ``bazaar``
256
 
   list only to inform plugin authors and package or installer managers.
257
 
 
258
 
   Once the installers are available, the mail can be sent to the
259
 
   ``bazaar-announce`` list too.
260
 
 
261
 
   For final releases, it should also be cc'd to ``info-gnu@gnu.org``,
262
 
   ``python-announce-list@python.org``, ``bug-directory@gnu.org``.
263
 
 
264
 
   In all cases, it is good to set ``Reply-To: bazaar@lists.canonical.com``,
265
 
   so that people who reply to the announcement don't spam other lists.
266
 
 
267
 
   The announce mail will look something like this::
268
 
 
269
 
      Subject: bzr x.yy released!
270
 
 
271
 
      <<Summary paragraph from news>>
272
 
 
273
 
      The Bazaar team is happy to announce availability of a new
274
 
      release of the bzr adaptive version control system.
275
 
      Bazaar is part of the GNU system <http://gnu.org/>.
276
 
 
277
 
      Thanks to everyone who contributed patches, suggestions, and
278
 
      feedback.
279
 
 
280
 
      Bazaar is now available for download from
281
 
      http://bazaar-vcs.org/Download as a source tarball; packages
282
 
      for various systems will be available soon.
283
 
 
284
 
      <<NEWS section from this release back to the last major release>>
285
 
 
286
 
   Feel free to tweak this to your taste.
287
 
 
288
 
#. Make an announcement through <https://launchpad.net/bzr/+announce>
289
 
 
290
 
#. Update the IRC channel topic. Use the ``/topic`` command to do this,
291
 
   ensuring the new topic text keeps the project name, web site link, etc.
292
 
 
293
 
#. Announce on http://freshmeat.net/projects/bzr/
294
 
 
295
 
   This should be done for beta releases, release candidates and final
296
 
   releases. If you do not have a Freshmeat account yet, ask one of the
297
 
   existing admins.
298
 
 
299
 
#. Update `<http://en.wikipedia.org/wiki/Bazaar_(software)>`_ -- this should
300
 
   be done for final releases but not for beta releases or Release Candidates.
301
 
 
302
 
#. Update the python package index: <http://pypi.python.org/pypi/bzr> - best
303
 
   done by running ::
304
 
 
305
 
       python setup.py register
306
 
 
307
 
   Remember to check the results afterwards.
308
 
 
309
 
   To be able to register the release you must create an account on
310
 
   <http://pypi.python.org/pypi> and have one of the existing owners of
311
 
   the project add you to the group.
312
 
 
313
 
 
314
 
Merging the released code back to trunk
315
 
---------------------------------------
316
 
 
317
 
Merge the release branch back into the trunk.  Check that changes in NEWS
318
 
were merged into the right sections.  If it's not already done, advance
319
 
the version number in ``bzr`` and ``bzrlib/__init__.py``.  Submit this
320
 
back into pqm for bzr.dev.
321
 
 
322
 
As soon as you change the version number in trunk, make sure you have
323
 
created the corresponding milestone to ensure the continuity in bug
324
 
targeting or nominating. Depending on the change, you may even have to
325
 
create a new series (if your change the major or minor release number), in
326
 
that case go to `Starting a cycle` and follow the instructions from there.
327
 
 
328
 
You should also merge (not pull) the release branch into
329
 
``lp:~bzr/bzr/current``, so that branch contains the current released code
330
 
at any time.
331
 
 
332
 
Releases until the final one
333
 
----------------------------
334
 
 
335
 
Congratulations - you have made your first release.  Have a beer
336
 
or fruit juice - it's on the house! If it was a beta, or
337
 
candidate, you're not finished yet. Another beta or candidate or
338
 
hopefully a final release is still to come.
339
 
 
340
 
The process is the same as for the first release. Goto `Starting the
341
 
release phase`_ and follow the instructions again. Some details change
342
 
between beta, candidate and final releases, but they should be
343
 
documented. If the instructions aren't clear enough, please fix them.
344
 
 
345
 
 
346
 
See also
347
 
--------
348
 
 
349
 
* `Packaging into the bzr PPA <ppa.html>`_ to make and publish Ubuntu
350
 
  packages.
351
 
* `Bazaar Developer Document Catalog <index.html>`_
352
 
* `Development cycles <cycle.html>`_: things that happen during the cycle
353
 
  before the actual release.
354
 
 
355
 
..
356
 
   vim: filetype=rst textwidth=74 ai shiftwidth=4