1e36a4865e3c9e53f1b657992ee225e492f6fa3d
[perl.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 is 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
351 Note that if this is a maint release, you should run the following actions
352 from the maint directory, but edit the C<Corelist.pm> in I<blead> and
353 subsequently cherry-pick it.
354
355 First, in order to update the C<%upstream> and C<%bug_tracker> hashes,
356 the C<Porting/corelist.pl> script requires you to have a local CPAN
357 mirror.  See http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN for
358 more details, but basically:
359
360     $ mkdir ~/cpan-mirror
361     $ rsync -av --delete ftp.funet.fi::CPAN ~/cpan-mirror/
362
363 (and re-run the rsync each time you need it to be up-to-date).
364 [XXX this really needs fixing to not require a whole CPAN mirror]
365
366 If necessary, bump C<$VERSION> (there's no need to do this for
367 every RC; in RC1, bump the version to a new clean number that will
368 appear in the final release, and leave as-is for the later RCs and final).
369
370 Then do
371
372     $ cd ~/perl/root; make perl
373     $ ./perl -Ilib Porting/corelist.pl ~/cpan-mirror/ > /tmp/corelist
374
375 This creates a file that looks something like
376
377     5.010001 => {
378         'AnyDBM_File'           => '1.00',
379         ...
380     },
381
382     %upstream = (
383         'App::Prove'            => undef,
384         ...
385     );
386
387     %bug_tracker = (
388         'App::Prove'            => 'http://rt.cpan.org/...',
389         ...
390     );
391
392 Cut and paste these tables into F<lib/Module/CoreList.pm>: the module
393 version list should be appended as the last entry in the C<%version> hash
394 (or replaced, if we've already added it for an earlier release candidate),
395 while the existing C<%upstream> and C<%bug_tracker> hashes should be
396 replaced with the new versions.
397
398 Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
399 entry, as that is likely to reflect the previous version number.
400
401 Then, add the current perl version to the C<CAVEATS> paragraph.
402
403 Add or update an entry to the C<%released> hash, including today's date
404 (if this is just a release candidate, set the date to '????-??-??').
405
406
407 =item *
408
409 Follow the instructions in the section L</"Building a snapshot">, then
410 carry on with the extra steps that follow here.
411
412 =item *
413
414 Wait for the smoke tests to catch up with the commit which this release is
415 based on (or at least the last commit of any consequence).
416
417 Then check that the smoke tests pass (particularly on Win32). If not, go
418 back and fix things.
419
420
421 =item *
422
423 Once smoking is okay, upload it to PAUSE. This is the point of no return.
424
425 XXX check whether need to upload .bz2,.meta, .readme too?
426
427 =item *
428
429 create a tag [XXX and branches and stuff ????], e.g.:
430
431     $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
432     $ git push origin tag perl-5.10.1-RC1
433
434 =item *
435
436 Mail p5p to announce it, with a quote you prepared earlier.
437
438 =item *
439
440 Wait 24 hours or so, then post the announcement to use.perl.org.
441
442 =back
443
444
445 =head2  Making a final release
446
447 At this point you should have a working release candidate with few or no
448 changes since.
449
450 It's essentially the same procedure as for making a release candidate, but
451 with a whole bunch of extra post-release steps.
452
453 =over 4
454
455 =item *
456
457 Follow the same steps as for making a release candidate, then
458
459 =item *
460
461 Ask Jarkko to update http://www.cpan.org/src/README.html and
462 Rafael to update http://dev.perl.org/perl5/
463
464
465 =item *
466
467 [ XXX disarm any patchlevel.h stuff ??? ]
468
469 =item *
470
471 Create a new empty perlNNNdelta.pod file for the current release + 1;
472 see F<Porting/how_to_write_a_perldelta.pod>.
473 [ XXX Perhaps we should have an empty template file we can copy in. ]
474
475 In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
476 entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
477 following files:
478
479     MANIFEST
480     pod/perl.pod
481     win32/pod.mak
482     vms/descrip_mms.template
483
484 (F<vms/descrip_mms.template> still needs a manual edit to bump the
485 C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
486
487 and change perlNNNdelta references to the new version in these files
488
489     INSTALL
490     win32/Makefile.mk
491     win32/Makefile
492     Makefile.SH
493     README
494
495 Also, edit the previous delta file to change the C<NAME> from C<perldelta>
496 to C<perlNNNdelta>.
497
498 These two lists of files probably aren't exhaustive; do a recursive grep
499 on the previous filename to look for suitable candidates.
500
501 (see 16410843ea for an example).
502
503 =item *
504
505 If this was a major release, bump the version, e.g. 5.12.0 to 5.13.0
506 [ XXX probably more complex stuff to do, including perldelta,
507 C<lib/feature.pm> ]
508
509 =item *
510
511 Copy the perlNNNdelta.pod for this release into the other branches, and
512 remember to update these files on those branches too:
513
514     MANIFEST
515     pod.lst
516     pod/perl.pod
517     vms/descrip_mms.template
518     win32/pod.mak
519
520 (see fc5be80860 for an example).
521
522 =item *
523
524 Make sure any recent F<pod/perlhist.pod> entries are copied to
525 F<perlhist.pod> on other branches; typically the RC* and final entries,
526 e.g.
527
528           5.8.9-RC1     2008-Nov-10
529           5.8.9-RC2     2008-Dec-06
530           5.8.9         2008-Dec-14
531
532 =item *
533
534 Remind the current maintainer of C<Module::CoreList> to push a new release
535 to CPAN.
536
537 =back
538
539 =head1 SOURCE
540
541 Based on
542 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
543 plus a whole bunch of other sources, including private correspondence.
544
545 =cut
546