This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
minor updates to release_managers_guide.pod
[perl5.git] / Porting / release_managers_guide.pod
CommitLineData
7277a900
GS
1
2=head1 NAME
3
4release_managers_guide - Releasing a new version of perl 5.x
5
f6af4394
DM
6XXX as of Jul 2009, this file is still a work-in-progress - DAPM
7
7277a900
GS
8=head1 SYNOPSIS
9
f6af4394
DM
10This document describes the series of tasks required - some automatic, some
11manual - to produce a perl release of some description, be that a snaphot,
12release candidate, or final release.
13
7277a900
GS
14The release process is primarily executed by the current pumpking.
15
1aff5354 16This document both helps as a check-list for the pumpking and is
7277a900
GS
17a base for ideas on how the various tasks could be automated or
18distributed.
19
f6af4394
DM
20The 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 ...
7277a900
GS
42
43=head1 DETAILS
44
7277a900 45
f6af4394
DM
46=head2 Building a snapshot
47
48A snapshot is intended to encourage in-depth testing from time-to-time,
49for example after a key point in the stabilisation of a branch. It
50requires less steps than a full release, and the version number of perl in
51the tarball will usually still be the old one.
52
53=over 4
54
55=item *
56
57As there are no regular smokes [ XXX yet - please fix?] find out about the
58state of VMS. If it's bad, think again.
59
60=item *
61
62Rebuild META.yml:
63
64 $ rm META.yml
65 $ make META.yml
66
67and commit it if it's changed.
68
69=item *
70
71Check that the manifest is sorted and correct:
72
73 $ make distclean
74 $ perl Porting/manisort
75 $ perl Porting/manicheck
76
77=item *
78
79If this is a release candidate or final release, add an entry to
80F<pod/perlhist.pod> with the current date, e.g.
81
82 5.8.9-RC1 2008-Nov-10
83
ce4f4fe2 84Make sure the correct pumpking is listed, and if this is your first time,
f6af4394
DM
85append your name to C<THE KEEPERS OF THE PUMPKIN>.
86
87=item *
88
89Build perl, then make sure it passes its own test suite, and installs.
90
91=item *
92
93Create a tarball. Use the C<-s> option to specify a suitable suffix for
94the 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
103This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
104the MANIFEST files into it, sets the correct permissions on them,
105adds DOS line endings to some, then tars it up as
106F<../perl-x.y.z-RC1.tar.gz>.
107
108XXX if we go for extra tags and branches stuff, then add the extra details
109here
110
111=item *
112
113Copy the tarball to a web server somewhere you have access to.
114
115=item *
116
117Download the tarball to some other machine (for a release candidate, to two or
118more servers: IRC is good for this).
119
120=item *
121
122Check that C<./Configure -des && make all test> works in one place.
123
124=item *
125
126Check that C<./Configure ... && make all test_harness install> works.
127
128=item *
129
130Check that the output of C<perl -v> and C<perl -V> are as expected,
131especially as regards version numbers, patch and/or RC levels, and @INC
132paths. Note that the results may be different without a F<.git/> directory,
133which is why you should test from the tarball.
134
135=item *
136
137Bootstrap the CPAN client on the clean install.
138
139=item *
140
141Install CPANPLUS.
142XXX pick something new; this is now bundled
143
144=item *
145
146Bootstrap the CPANPLUS client.
147
148=item *
149
150Install an XS module.
151
152=item *
153
154If all is well, announce the snaphot to p5p. (For a release candidate,
155instead follow the further steps described later.)
156
157=back
158
159=head2 Actions prior to the first release candidate
160
161A week or two before the first release candidate, there are some additional
162tasks you should perform (actually, some of these should be done regularly
163anyway, but they definitely need doing now):
7277a900
GS
164
165=over 4
166
f6af4394
DM
167=item *
168
169Check F<Maintainers.pl> for consistency; both these commands should
170produce no output:
171
172 perl Porting/Maintainers --checkmani
173 perl Porting/Maintainers --checkmani lib/ ext/
174
175=item *
176
177Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
178run the following:
179
180 ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
7277a900 181
f6af4394
DM
182to see any inconsistencies between the core and CPAN versions of distros,
183then fix the core, or cajole CPAN authors as appropriate. See also the
184C<-d> and C<-v> options for more detail. You'll probably want to use the
185C<-c cachedir> option to avoid repeated CPAN downloads.
7277a900 186
f6af4394 187To see which core distro versions differ from the current CPAN versions:
7277a900 188
f6af4394 189 ./perl -Ilib Porting/core-cpan-diff -x -a
7277a900 190
f6af4394 191=item *
7277a900 192
f6af4394 193Ensure dual-life CPAN modules are stable, which comes down to:
7277a900
GS
194
195 for each module that fails its regression tests on $current
f6af4394
DM
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)
7277a900
GS
199
200 attempt to group failure causes
201
202 for each failure cause
f6af4394
DM
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)
1aff5354 212
f6af4394 213=item *
7277a900 214
f6af4394 215Similarly, monitor the smoking of core tests, and try to fix.
7277a900 216
f6af4394 217=item *
7277a900 218
f6af4394
DM
219Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
220previous version to check for for modules that have identical version
221numbers but different contents, e.g.:
7277a900 222
f6af4394
DM
223 $ cd ~/some-perl-root
224 $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 .
225
226then bump the version numbers of any non-dual-life modules that have
227changed since the previous release, but which still have the old version
228number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x),
229then compare against both.
230
231Note that some of the files listed may be generated (e.g. copied from ext/
232to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm);
233make sure you edit the correct file!
234
235Once all version numbers have been bumped, re-run the checks.
236
237Then run again without the -x option, to check that dual-life modules are
238also sensible.
239
240
241=item *
242
243Get perldelta in a mostly finished state.
244XXX expand
245
246=item *
247
248Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
249
250There is a tool to semi-automate this process. It works in two stages.
251First, it generates a list of suggested changes, which you review and
252edit; then you feed this list back and it applies the edits. So, first
253scan the source dir looking for likely candidates:
254
255 $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
256
257This 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
264i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
265Review the file carefully, and delete any -/+ line pairs that you don't
266want changing. Remember that this tool is largely just grepping for '5.10.0'
267or whatever, so it will generate false positives. Be careful not change
268text like "this was fixed in 5.10.0"! Then run:
269
270 $ Porting/bump-perl-version -u < /tmp/scan
271
272which will update all the files shown; then commit the changes.
273
274Be particularly careful with F<INSTALL>, which contains a mixture of
275C<5.10.0>-type strings, some of which need bumping on every release, and
276some of which need to be left. Also note that this tool currently only
277performs a single change per line, so in particular, this line in
278README.vms needs special handling:
279
280 rename perl-5^.10^.1.dir perl-5_10_1.dir
7277a900 281
f6af4394 282=item *
7277a900 283
f6af4394
DM
284Update the F<Changes> file to contain the git log command which would show
285all the changes in this release. You will need assume the existence of a
286not-yet created tag for the forthcoming release; e.g.
7277a900 287
f6af4394 288 git log ... perl-5.10.0..perl5.12.0
7277a900 289
f6af4394
DM
290Due to warts in the perforce-to-git migration, some branches require extra
291exclusions to avoid other branches being pulled in. Make sure you have the
292correct incantation: replace the not-yet-created tag with C<HEAD> and see
293if git log produces roughly the right number of commits across roughly the
294right time period.
7277a900 295
f6af4394 296=item *
7277a900 297
f6af4394 298Check some more build configurations, e.g.
7277a900 299
f6af4394
DM
300 -Duseshrplib -Dd_dosuid
301 make suidperl
7277a900 302
f6af4394
DM
303Check that setuid installs works (for < 5.11.0 only).
304XXX any other configs?
7277a900 305
f6af4394 306=item *
7277a900 307
f6af4394
DM
308Make sure you have a PAUSE account suitable for uploading a perl release.
309If you don't have a PAUSE account, then request one:
7277a900 310
f6af4394 311 https://pause.perl.org/pause/query?ACTION=request_id
7277a900 312
f6af4394
DM
313Check that your account is allowed to upload perl distros: goto
314https://pause.perl.org/, login, then select 'upload file to CPAN'; there
315should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas
316to add your ID to the list of people allowed to upload something called
317perl.
7277a900 318
f6af4394 319=item *
7277a900 320
f6af4394
DM
321Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
322necessary, update the script to include new alias mappings.
7277a900 323
f6af4394
DM
324XXX This script is currently broken (7/2009). It needs updating to work
325with 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
332L</"Actions prior to the first release candidate">.)
333
334=over 4
335
336=item *
337
338Re-read the perldelta to try to find any embarrassing typos and thinkos;
339remove any C<TODO> or C<XXX> flags; and run through pod and spell
340checkers. [XXX show how]
341
342=item *
343
344Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
345final release, remove it. [ XXX how now?? see 34813 for old way ]
346
347=item *
348
349Update C<Module::Corelist>.
210de33e 350
ce4f4fe2 351Note that if this is a maint release, you should run the following actions
210de33e
DM
352from the maint directory, but edit the C<Corelist.pm> in I<blead> and
353subsequently cherry-pick it.
354
355First, in order to update the C<%upstream> and C<%bug_tracker> hashes,
356the C<Porting/corelist.pl> script requires you to have a local CPAN
357mirror. See http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN for
358more 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
366If necessary, bump C<$VERSION> (there's no need to do this for
367every RC; in RC1, bump the version to a new clean number that will
368appear in the final release, and leave as-is for the later RCs and final).
369
370Then do
371
372 $ cd ~/perl/root; make perl
373 $ ./perl -Ilib Porting/corelist.pl ~/cpan-mirror/ > /tmp/corelist
374
375This 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
210de33e
DM
392Cut and paste these tables into F<lib/Module/CoreList.pm>: the module
393version 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),
395while the existing C<%upstream> and C<%bug_tracker> hashes should be
396replaced with the new versions.
397
ce4f4fe2 398Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
210de33e
DM
399entry, as that is likely to reflect the previous version number.
400
401Then, add the current perl version to the C<CAVEATS> paragraph.
402
403Add 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
7277a900 406
f6af4394
DM
407=item *
408
409Follow the instructions in the section L</"Building a snapshot">, then
410carry on with the extra steps that follow here.
411
412=item *
7277a900 413
addebd58
DM
414Disarm the patchlevel.h change [ XXX expand ]
415
416=item *
417
f6af4394
DM
418Wait for the smoke tests to catch up with the commit which this release is
419based on (or at least the last commit of any consequence).
7277a900 420
f6af4394
DM
421Then check that the smoke tests pass (particularly on Win32). If not, go
422back and fix things.
7277a900 423
7277a900 424
f6af4394 425=item *
7277a900 426
f6af4394 427Once smoking is okay, upload it to PAUSE. This is the point of no return.
addebd58 428You may wish to create a .bz2 version of the tarball and upload that too.
f6af4394 429
210de33e
DM
430=item *
431
432create a tag [XXX and branches and stuff ????], e.g.:
433
434 $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
435 $ git push origin tag perl-5.10.1-RC1
f6af4394
DM
436
437=item *
438
439Mail p5p to announce it, with a quote you prepared earlier.
440
441=item *
442
443Wait 24 hours or so, then post the announcement to use.perl.org.
addebd58
DM
444(if you don't have access rights to post news, ask someone like Rafael to
445do it for you.)
f6af4394
DM
446
447=back
448
449
450=head2 Making a final release
451
452At this point you should have a working release candidate with few or no
453changes since.
454
455It's essentially the same procedure as for making a release candidate, but
456with a whole bunch of extra post-release steps.
457
458=over 4
7277a900 459
f6af4394 460=item *
7277a900 461
f6af4394 462Follow the same steps as for making a release candidate, then
7277a900 463
f6af4394 464=item *
7277a900 465
f6af4394
DM
466Ask Jarkko to update http://www.cpan.org/src/README.html and
467Rafael to update http://dev.perl.org/perl5/
7277a900 468
f6af4394 469=item *
7277a900 470
f6af4394
DM
471Create a new empty perlNNNdelta.pod file for the current release + 1;
472see F<Porting/how_to_write_a_perldelta.pod>.
473[ XXX Perhaps we should have an empty template file we can copy in. ]
7277a900 474
a2cba4bc
NC
475In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
476entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
477following files:
7277a900 478
f6af4394 479 MANIFEST
f6af4394 480 pod/perl.pod
a2cba4bc
NC
481 win32/pod.mak
482 vms/descrip_mms.template
483
484(F<vms/descrip_mms.template> still needs a manual edit to bump the
485C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
7277a900 486
f6af4394 487and change perlNNNdelta references to the new version in these files
7277a900 488
f6af4394
DM
489 INSTALL
490 win32/Makefile.mk
491 win32/Makefile
492 Makefile.SH
493 README
7277a900 494
f6af4394
DM
495Also, edit the previous delta file to change the C<NAME> from C<perldelta>
496to C<perlNNNdelta>.
7277a900 497
f6af4394
DM
498These two lists of files probably aren't exhaustive; do a recursive grep
499on the previous filename to look for suitable candidates.
7277a900 500
f6af4394 501(see 16410843ea for an example).
7277a900 502
f6af4394 503=item *
7277a900 504
addebd58
DM
505If this was a major release, then
506
507=over
508
509=item *
510
511bump the version, e.g. 5.12.0 to 5.13.0;
512
513=item *
514
515[ XXX probably lots more stuff to do, including perldelta,
f6af4394 516C<lib/feature.pm> ]
7277a900 517
f6af4394 518=item *
7277a900 519
addebd58
DM
520Create a new maint branch with an empty Porting/mergelog file
521[ XXX and lots of other stuff too, probably ]
522
523=back
524
525=item *
526
f6af4394
DM
527Copy the perlNNNdelta.pod for this release into the other branches, and
528remember to update these files on those branches too:
7277a900 529
f6af4394
DM
530 MANIFEST
531 pod.lst
532 pod/perl.pod
533 vms/descrip_mms.template
534 win32/pod.mak
7277a900 535
f6af4394 536(see fc5be80860 for an example).
7277a900 537
f6af4394 538=item *
7277a900 539
f6af4394
DM
540Make sure any recent F<pod/perlhist.pod> entries are copied to
541F<perlhist.pod> on other branches; typically the RC* and final entries,
542e.g.
7277a900 543
f6af4394
DM
544 5.8.9-RC1 2008-Nov-10
545 5.8.9-RC2 2008-Dec-06
546 5.8.9 2008-Dec-14
7277a900 547
6e40fbf9
DM
548=item *
549
550Remind the current maintainer of C<Module::CoreList> to push a new release
551to CPAN.
552
7277a900
GS
553=back
554
555=head1 SOURCE
556
f6af4394
DM
557Based on
558http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
559plus a whole bunch of other sources, including private correspondence.
7277a900
GS
560
561=cut
562