This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
5bc1ff24b7f8fca5e4a43e28a9c39d8c10504cc3
[perl5.git] / Porting / release_managers_guide.pod
1
2 =head1 NAME
3
4 release_managers_guide - Releasing a new version of perl 5.x
5
6 XXX as of Jul 2009, this file is still a work-in-progress - DAPM
7
8 =head1 SYNOPSIS
9
10 This document describes the series of tasks required - some automatic, some
11 manual - to produce a perl release of some description, be that a snaphot,
12 release candidate, or final release.
13
14 The release process is primarily executed by the current pumpking.
15
16 This document both helps as a check-list for the pumpking and is
17 a base for ideas on how the various tasks could be automated or 
18 distributed.
19
20 The outline of a release cycle is as follows:
21
22     (5.10.1 is released, and post-release action have been done)
23
24     ...time passes...
25
26     an occasional snapshot is released, that still identifies itself as
27         5.10.1
28
29     ...time passes...
30
31     a few weeks before the release, a number of steps are performed,
32         including bumping the version to 5.10.2
33     
34     perl-5.10.2-RC1 is released
35
36     perl-5.10.2 is released
37
38     post-release actions are performed, including creating new
39         perl5103delta.pod
40
41     ... the cycle continues ...
42
43 =head1 DETAILS
44
45
46 =head2 Building a snapshot
47
48 A snapshot is intended to encourage in-depth testing from time-to-time,
49 for example after a key point in the stabilisation of a branch. It
50 requires less steps than a full release, and the version number of perl in
51 the tarball will usually still be the old one.
52
53 =over 4
54
55 =item *
56
57 As there are no regular smokes [ XXX yet - please fix?] find out about the
58 state of VMS. If it's bad, think again.
59
60 =item *
61
62 Rebuild META.yml:
63
64     $ rm META.yml
65     $ make META.yml
66
67 and commit it if it's changed.
68
69 =item *
70
71 Check that the manifest is sorted and correct:
72
73     $ make distclean 
74     $ perl Porting/manisort
75     $ perl Porting/manicheck
76
77 =item *
78
79 If this is a release candidate or final release, add an entry to
80 F<pod/perlhist.pod> with the current date, e.g.
81
82           5.8.9-RC1     2008-Nov-10
83
84 Make sure the correct pumpking is listed, and if this your first time,
85 append your name to C<THE KEEPERS OF THE PUMPKIN>.
86
87 =item *
88
89 Build perl, then make sure it passes its own test suite, and installs.
90
91 =item *
92
93 Create a tarball. Use the C<-s> option to specify a suitable suffix for
94 the tarball and directory name:
95
96     $ cd root/of/perl/tree
97     $ git clean -xdf            #  make sure perl and git agree on files
98
99     $ perl Porting/makerel -s `git describe` # for a snapshot
100     $ perl Porting/makerel -s RC1            # for a release candidate
101     $ perl Porting/makerel                   # for a final release
102
103 This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
104 the MANIFEST files into it, sets the correct permissions on them,
105 adds DOS line endings to some, then tars it up as
106 F<../perl-x.y.z-RC1.tar.gz>.
107
108 XXX if we go for extra tags and branches stuff, then add the extra details
109 here
110
111 =item *
112
113 Copy the tarball to a web server somewhere you have access to.
114
115 =item *
116
117 Download the tarball to some other machine (for a release candidate, to two or
118 more servers: IRC is good for this).
119
120 =item *
121
122 Check that C<./Configure -des && make all test> works in one place.
123
124 =item *
125
126 Check that C<./Configure ... && make all test_harness install> works.
127
128 =item *
129
130 Check that the output of C<perl -v> and C<perl -V> are as expected,
131 especially as regards version numbers, patch and/or RC levels, and @INC
132 paths. Note that the results may be different without a F<.git/> directory,
133 which is why you should test from the tarball.
134
135 =item *
136
137 Bootstrap the CPAN client on the clean install.
138
139 =item *
140
141 Install CPANPLUS.
142 XXX pick something new; this is now bundled
143
144 =item *
145
146 Bootstrap the CPANPLUS client.
147
148 =item *
149
150 Install an XS module.
151
152 =item *
153
154 If all is well, announce the snaphot to p5p. (For a release candidate,
155 instead follow the further steps described later.)
156
157 =back
158
159 =head2  Actions prior to the first release candidate
160
161 A week or two before the first release candidate, there are some additional
162 tasks you should perform (actually, some of these should be done regularly
163 anyway, but they definitely need doing now):
164
165 =over 4
166
167 =item *
168
169 Check F<Maintainers.pl> for consistency; both these commands should
170 produce no output:
171
172     perl Porting/Maintainers --checkmani
173     perl Porting/Maintainers --checkmani lib/ ext/
174
175 =item *
176
177 Ensure that dual-life CPAN modules are synchronised with CPAN.  Basically,
178 run the following:
179
180     ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
181
182 to see any inconsistencies between the core and CPAN versions of distros,
183 then fix the core, or cajole CPAN authors as appropriate. See also the
184 C<-d> and C<-v> options for more detail.  You'll probably want to use the
185 C<-c cachedir> option to avoid repeated CPAN downloads.
186
187 To see which core distro versions differ from the current CPAN versions:
188
189     ./perl -Ilib Porting/core-cpan-diff -x -a
190
191 =item *
192
193 Ensure dual-life CPAN modules are stable, which comes down to:
194
195     for each module that fails its regression tests on $current
196         did it fail identically on $previous?
197         if yes, "SEP" (Somebody Else's Problem)
198         else work out why it failed (a bisect is useful for this)
199
200     attempt to group failure causes
201
202     for each failure cause
203         is that a regression?
204         if yes, figure out how to fix it
205             (more code? revert the code that broke it)
206         else
207             (presumably) it's relying on something un-or-under-documented
208             should the existing behaviour stay?
209                 yes - goto "regression"
210                 no - note it in perldelta as a significant bugfix
211                 (also, try to inform the module's author)
212
213 =item *
214
215 Similarly, monitor the smoking of core tests, and try to fix.
216
217 =item *
218
219 Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
220 previous version to check for for modules that have identical version
221 numbers but different contents, e.g.:
222
223      $ cd ~/some-perl-root
224      $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 .
225
226 then bump the version numbers of any non-dual-life modules that have
227 changed since the previous release, but which still have the old version
228 number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x),
229 then compare against both.
230
231 Note that some of the files listed may be generated (e.g. copied from ext/
232 to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm);
233 make sure you edit the correct file!
234
235 Once all version numbers have been bumped, re-run the checks.
236
237 Then run again without the -x option, to check that dual-life modules are
238 also sensible.
239
240
241 =item *
242
243 Get perldelta in a mostly finished state.
244 XXX expand
245
246 =item *
247
248 Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
249
250 There is a tool to semi-automate this process. It works in two stages.
251 First, it generates a list of suggested changes, which you review and
252 edit; then you feed this list back and it applies the edits. So, first
253 scan the source dir looking for likely  candidates:
254
255     $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
256
257 This produces a file containing a list of suggested edits, eg:
258
259     NetWare/Makefile
260
261        89: -MODULE_DESC     = "Perl 5.10.0 for NetWare"
262            +MODULE_DESC     = "Perl 5.10.1 for NetWare"
263
264 i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
265 Review the file carefully, and delete any -/+ line pairs that you don't
266 want changing. Remember that this tool is largely just grepping for '5.10.0'
267 or whatever, so it will generate false positives. Be careful not change
268 text like "this was fixed in 5.10.0"! Then run:
269
270     $ Porting/bump-perl-version -u < /tmp/scan
271
272 which will update all the files shown; then commit the changes.
273
274 Be particularly careful with F<INSTALL>, which contains a mixture of
275 C<5.10.0>-type strings, some of which need bumping on every release, and
276 some of which need to be left. Also note that this tool currently only
277 performs a single change per line, so in particular, this line in
278 README.vms needs special handling:
279
280     rename perl-5^.10^.1.dir perl-5_10_1.dir
281
282 =item *
283
284 Update the F<Changes> file to contain the git log command which would show
285 all the changes in this release. You will need assume the existence of a
286 not-yet created tag for the forthcoming release; e.g.
287
288     git log ... perl-5.10.0..perl5.12.0
289
290 Due to warts in the perforce-to-git migration, some branches require extra
291 exclusions to avoid other branches being pulled in. Make sure you have the
292 correct incantation: replace the not-yet-created tag with C<HEAD> and see
293 if git log produces roughly the right number of commits across roughly the
294 right time period.
295
296 =item *
297
298 Check some more build configurations, e.g.
299
300      -Duseshrplib -Dd_dosuid
301      make suidperl
302
303 Check that setuid installs works (for < 5.11.0 only).
304 XXX any other configs?
305
306 =item *
307
308 Make sure you have a PAUSE account suitable for uploading a perl release.
309 If you don't have a PAUSE account, then request one:
310
311     https://pause.perl.org/pause/query?ACTION=request_id
312
313 Check that your account is allowed to upload perl distros: goto
314 https://pause.perl.org/, login, then select 'upload file to CPAN'; there
315 should be a "For pumpkings only: Send a CC" tickbox.  If not, ask Andreas
316 to add your ID to the list of people allowed to upload something called
317 perl.
318
319 =item *
320
321 Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
322 necessary, update the script to include new alias mappings.
323
324 XXX This script is currently broken (7/2009). It needs updating to work
325 with git and a lack of Changes files.
326
327 =back
328
329 =head2  Building a release candidate
330
331 (At this point you should already have performed the actions described in
332 L</"Actions prior to the first release candidate">.)
333
334 =over 4
335
336 =item *
337
338 Re-read the perldelta to try to find any embarrassing typos and thinkos;
339 remove any C<TODO> or C<XXX> flags; and run through pod and spell
340 checkers.   [XXX show how]
341
342 =item *
343
344 Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
345 final release, remove it.  [ XXX how now?? see 34813 for old way ]
346
347 =item *
348
349 Update C<Module::Corelist>.
350 [XXX add how: presumably Porting/corelist.pl ]
351 but we need to fix that: 
352 it has been holding perforce revisions for releases, but we can't know
353 hashes in advance for git. We need to agree a plan to move to git tags]
354
355 =item *
356
357 Follow the instructions in the section L</"Building a snapshot">, then
358 carry on with the extra steps that follow here.
359
360 =item *
361
362 Wait for the smoke tests to catch up with the commit which this release is
363 based on (or at least the last commit of any consequence).
364
365 Then check that the smoke tests pass (particularly on Win32). If not, go
366 back and fix things.
367
368
369 =item *
370
371 Once smoking is okay, upload it to PAUSE. This is the point of no return.
372
373 XXX check whether need to upload .bz2,.meta, .readme too?
374
375
376 =item *
377
378 Mail p5p to announce it, with a quote you prepared earlier.
379
380 =item *
381
382 Wait 24 hours or so, then post the announcement to use.perl.org.
383
384 =back
385
386
387 =head2  Making a final release
388
389 At this point you should have a working release candidate with few or no
390 changes since.
391
392 It's essentially the same procedure as for making a release candidate, but
393 with a whole bunch of extra post-release steps.
394
395 =over 4
396
397 =item *
398
399 Follow the same steps as for making a release candidate, then
400
401 =item *
402
403 Ask Jarkko to update http://www.cpan.org/src/README.html and
404 Rafael to update http://dev.perl.org/perl5/
405
406
407 =item *
408
409 create a tag [XXX and branches and stuff?]
410 [ XXX expand this ]
411
412 =item *
413
414 [ XXX disarm any patchlevel.h stuff ??? ]
415
416 =item *
417
418 Create a new empty perlNNNdelta.pod file for the current release + 1;
419 see F<Porting/how_to_write_a_perldelta.pod>.
420 [ XXX Perhaps we should have an empty template file we can copy in. ]
421
422 In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
423 entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
424 following files:
425
426     MANIFEST
427     pod/perl.pod
428     win32/pod.mak
429     vms/descrip_mms.template
430
431 (F<vms/descrip_mms.template> still needs a manual edit to bump the
432 C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
433
434 and change perlNNNdelta references to the new version in these files
435
436     INSTALL
437     win32/Makefile.mk
438     win32/Makefile
439     Makefile.SH
440     README
441
442 Also, edit the previous delta file to change the C<NAME> from C<perldelta>
443 to C<perlNNNdelta>.
444
445 These two lists of files probably aren't exhaustive; do a recursive grep
446 on the previous filename to look for suitable candidates.
447
448 (see 16410843ea for an example).
449
450 =item *
451
452 If this was  major release, bump the version, e.g. 5.12.0 to 5.13.0
453 [ XXX probably more complex stuff to do, including perldelta,
454 C<lib/feature.pm> ]
455
456 =item *
457
458 Copy the perlNNNdelta.pod for this release into the other branches, and
459 remember to update these files on those branches too:
460
461     MANIFEST
462     pod.lst
463     pod/perl.pod
464     vms/descrip_mms.template
465     win32/pod.mak
466
467 (see fc5be80860 for an example).
468
469 =item *
470
471 Make sure any recent F<pod/perlhist.pod> entries are copied to
472 F<perlhist.pod> on other branches; typically the RC* and final entries,
473 e.g.
474
475           5.8.9-RC1     2008-Nov-10
476           5.8.9-RC2     2008-Dec-06
477           5.8.9         2008-Dec-14
478
479 =back
480
481 =head1 SOURCE
482
483 Based on
484 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
485 plus a whole bunch of other sources, including private correspondence.
486
487 =cut
488