This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clean up the .exists files on VMS.
[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
636a1918
DM
6XXX as of Jul 2009, this file is still a work-in-progress. I think it
7contains all the actions needed to build a release, but things may have
8got skipped, and some things could do with polishing. Note that things
9change each release, there may be new things not covered here, or
10tools may need updating. DAPM
f6af4394 11
7277a900
GS
12=head1 SYNOPSIS
13
f6af4394
DM
14This document describes the series of tasks required - some automatic, some
15manual - to produce a perl release of some description, be that a snaphot,
16release candidate, or final release.
17
7277a900
GS
18The release process is primarily executed by the current pumpking.
19
1aff5354 20This document both helps as a check-list for the pumpking and is
7277a900
GS
21a base for ideas on how the various tasks could be automated or
22distributed.
23
636a1918 24The outline of a typical release cycle is as follows:
f6af4394 25
636a1918 26 (5.10.1 is released, and post-release actions have been done)
f6af4394
DM
27
28 ...time passes...
29
30 an occasional snapshot is released, that still identifies itself as
31 5.10.1
32
33 ...time passes...
34
35 a few weeks before the release, a number of steps are performed,
36 including bumping the version to 5.10.2
636a1918
DM
37
38 ...a few weeks passes...
46743ef7 39
f6af4394
DM
40 perl-5.10.2-RC1 is released
41
42 perl-5.10.2 is released
43
44 post-release actions are performed, including creating new
45 perl5103delta.pod
46
47 ... the cycle continues ...
7277a900
GS
48
49=head1 DETAILS
50
7277a900 51
f6af4394
DM
52=head2 Building a snapshot
53
54A snapshot is intended to encourage in-depth testing from time-to-time,
55for example after a key point in the stabilisation of a branch. It
56requires less steps than a full release, and the version number of perl in
57the tarball will usually still be the old one.
58
59=over 4
60
61=item *
62
63As there are no regular smokes [ XXX yet - please fix?] find out about the
64state of VMS. If it's bad, think again.
65
66=item *
67
46743ef7
JV
68Configure and build perl so that you have a Makefile and porting tools:
69
70 $ ./Configure -Dusedevel -des
71 $ make
72
73=item *
74
f6af4394
DM
75Rebuild META.yml:
76
77 $ rm META.yml
78 $ make META.yml
79
46743ef7
JV
80Commit META.yml if it has changed:
81
82 $ git commit -m 'Updating META.yml in preparation for release of 5.x.y' META.yml
f6af4394
DM
83
84=item *
85
86Check that the manifest is sorted and correct:
87
46743ef7 88 $ make manisort
f6af4394 89 $ make distclean
f6af4394
DM
90 $ perl Porting/manicheck
91
46743ef7
JV
92
93Commit MANIFEST if it has changed:
94
95 $ git commit -m 'Updating MANIFEST in preparation for release of 5.x.y' MANIFEST
96
97
98
f6af4394
DM
99=item *
100
101If this is a release candidate or final release, add an entry to
102F<pod/perlhist.pod> with the current date, e.g.
103
104 5.8.9-RC1 2008-Nov-10
105
ce4f4fe2 106Make sure the correct pumpking is listed, and if this is your first time,
f6af4394
DM
107append your name to C<THE KEEPERS OF THE PUMPKIN>.
108
109=item *
110
111Build perl, then make sure it passes its own test suite, and installs.
112
46743ef7
JV
113 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
114 $ make test install
115
f6af4394
DM
116=item *
117
118Create a tarball. Use the C<-s> option to specify a suitable suffix for
119the tarball and directory name:
120
121 $ cd root/of/perl/tree
46743ef7 122 $ make distclean
f6af4394
DM
123 $ git clean -xdf # make sure perl and git agree on files
124
85bdf03b
DM
125 $ perl Porting/makerel -b -s `git describe` # for a snapshot
126 $ perl Porting/makerel -b -s RC1 # for a release candidate
127 $ perl Porting/makerel -b # for a final release
f6af4394
DM
128
129This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
130the MANIFEST files into it, sets the correct permissions on them,
131adds DOS line endings to some, then tars it up as
85bdf03b 132F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
f6af4394
DM
133
134XXX if we go for extra tags and branches stuff, then add the extra details
135here
136
137=item *
138
85bdf03b
DM
139Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
140have access to.
f6af4394
DM
141
142=item *
143
46743ef7
JV
144Download the tarball to some other machine. For a release candidate,
145you really want to test your tarball on two or more different platforms
146and architectures. The #p5p IRC channel on irc.perl.org is a good place
147to find willing victims.
f6af4394
DM
148
149=item *
150
46743ef7
JV
151Check that C<./Configure -des && make all test> works on each test
152machine.
f6af4394
DM
153
154=item *
155
156Check that C<./Configure ... && make all test_harness install> works.
157
158=item *
159
160Check that the output of C<perl -v> and C<perl -V> are as expected,
161especially as regards version numbers, patch and/or RC levels, and @INC
46743ef7
JV
162paths.
163
164Note that the results may be different without a F<.git/> directory,
f6af4394
DM
165which is why you should test from the tarball.
166
167=item *
168
169Bootstrap the CPAN client on the clean install.
170
171=item *
172
46743ef7 173Install Inline.pm
f6af4394 174
46743ef7 175 perl -MCPAN -e'install Inline'
9db5571e 176
46743ef7 177Check that your perl can run this:
9db5571e 178
46743ef7 179 perl -lwe 'use Inline C => "int answer() { return 42;} "; print answer'
9db5571e 180
f6af4394
DM
181=item *
182
183Bootstrap the CPANPLUS client.
184
185=item *
186
187Install an XS module.
188
189=item *
190
85bdf03b 191If all is well, announce the snapshot to p5p. (For a release candidate,
f6af4394
DM
192instead follow the further steps described later.)
193
194=back
195
196=head2 Actions prior to the first release candidate
197
198A week or two before the first release candidate, there are some additional
199tasks you should perform (actually, some of these should be done regularly
200anyway, but they definitely need doing now):
7277a900
GS
201
202=over 4
203
f6af4394
DM
204=item *
205
206Check F<Maintainers.pl> for consistency; both these commands should
207produce no output:
208
209 perl Porting/Maintainers --checkmani
210 perl Porting/Maintainers --checkmani lib/ ext/
211
212=item *
213
214Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
215run the following:
216
217 ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
7277a900 218
f6af4394
DM
219to see any inconsistencies between the core and CPAN versions of distros,
220then fix the core, or cajole CPAN authors as appropriate. See also the
221C<-d> and C<-v> options for more detail. You'll probably want to use the
222C<-c cachedir> option to avoid repeated CPAN downloads.
7277a900 223
f6af4394 224To see which core distro versions differ from the current CPAN versions:
7277a900 225
f6af4394 226 ./perl -Ilib Porting/core-cpan-diff -x -a
7277a900 227
636a1918
DM
228if you are making a maint release, run C<core-cpan-diff> on both blead and
229maint, then diff the two outputs. Compare this with what you expect, and if
230necessary, fix things up. For example, you might think that both blead
231and maint are synchronised with a particular CPAN module, but one might
232have some extra changes.
233
f6af4394 234=item *
7277a900 235
f6af4394 236Ensure dual-life CPAN modules are stable, which comes down to:
7277a900
GS
237
238 for each module that fails its regression tests on $current
f6af4394
DM
239 did it fail identically on $previous?
240 if yes, "SEP" (Somebody Else's Problem)
241 else work out why it failed (a bisect is useful for this)
7277a900
GS
242
243 attempt to group failure causes
244
245 for each failure cause
f6af4394
DM
246 is that a regression?
247 if yes, figure out how to fix it
248 (more code? revert the code that broke it)
249 else
250 (presumably) it's relying on something un-or-under-documented
251 should the existing behaviour stay?
252 yes - goto "regression"
253 no - note it in perldelta as a significant bugfix
254 (also, try to inform the module's author)
1aff5354 255
f6af4394 256=item *
7277a900 257
f6af4394 258Similarly, monitor the smoking of core tests, and try to fix.
7277a900 259
f6af4394 260=item *
7277a900 261
636a1918
DM
262Similarly, monitor the smoking of perl for compiler warnings, and try to
263fix.
264
265=item *
266
f6af4394
DM
267Run F<Porting/cmpVERSION.pl> to compare the current source tree with the
268previous version to check for for modules that have identical version
269numbers but different contents, e.g.:
7277a900 270
f6af4394
DM
271 $ cd ~/some-perl-root
272 $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 .
273
274then bump the version numbers of any non-dual-life modules that have
275changed since the previous release, but which still have the old version
276number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x),
277then compare against both.
278
279Note that some of the files listed may be generated (e.g. copied from ext/
280to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm);
281make sure you edit the correct file!
282
283Once all version numbers have been bumped, re-run the checks.
284
285Then run again without the -x option, to check that dual-life modules are
286also sensible.
287
55878aed
JV
288=item *
289
290Check that files managed by F<regen.pl> and friends are up to date. From
291within your working directory:
292
293
ee56566f 294 $ git status
55878aed
JV
295 $ make regen
296 $ make regen_perly
ee56566f 297 $ git status
55878aed
JV
298
299If any of the files managed by regen.pl have changed, then you should commit
300the updated versions:
301
302 $ git commit -m 'Updated files generated by regen tools for perl 5.x.y' <list of files>
303
f6af4394
DM
304
305=item *
306
307Get perldelta in a mostly finished state.
636a1918
DM
308Peruse F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
309every section it lists is, if necessary, populated and complete. Copy
310edit the whole document.
f6af4394
DM
311
312=item *
313
314Bump the perl version number (e.g. from 5.10.0 to 5.10.1).
315
316There is a tool to semi-automate this process. It works in two stages.
317First, it generates a list of suggested changes, which you review and
318edit; then you feed this list back and it applies the edits. So, first
319scan the source dir looking for likely candidates:
320
321 $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
322
323This produces a file containing a list of suggested edits, eg:
324
325 NetWare/Makefile
326
327 89: -MODULE_DESC = "Perl 5.10.0 for NetWare"
328 +MODULE_DESC = "Perl 5.10.1 for NetWare"
329
330i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
331Review the file carefully, and delete any -/+ line pairs that you don't
332want changing. Remember that this tool is largely just grepping for '5.10.0'
333or whatever, so it will generate false positives. Be careful not change
334text like "this was fixed in 5.10.0"! Then run:
335
336 $ Porting/bump-perl-version -u < /tmp/scan
337
338which will update all the files shown; then commit the changes.
339
340Be particularly careful with F<INSTALL>, which contains a mixture of
341C<5.10.0>-type strings, some of which need bumping on every release, and
342some of which need to be left. Also note that this tool currently only
343performs a single change per line, so in particular, this line in
344README.vms needs special handling:
345
346 rename perl-5^.10^.1.dir perl-5_10_1.dir
7277a900 347
dc0a62a1
DM
348
349=item *
350
351Review and update INSTALL to account for the change in version number;
352in particular, the "Coexistence with earlier versions of perl 5" section.
353
f6af4394 354=item *
7277a900 355
f6af4394
DM
356Update the F<Changes> file to contain the git log command which would show
357all the changes in this release. You will need assume the existence of a
358not-yet created tag for the forthcoming release; e.g.
7277a900 359
f6af4394 360 git log ... perl-5.10.0..perl5.12.0
7277a900 361
f6af4394
DM
362Due to warts in the perforce-to-git migration, some branches require extra
363exclusions to avoid other branches being pulled in. Make sure you have the
364correct incantation: replace the not-yet-created tag with C<HEAD> and see
365if git log produces roughly the right number of commits across roughly the
366right time period.
7277a900 367
dc0a62a1 368
f6af4394 369=item *
7277a900 370
f6af4394 371Check some more build configurations, e.g.
7277a900 372
f6af4394
DM
373 -Duseshrplib -Dd_dosuid
374 make suidperl
7277a900 375
f6af4394
DM
376Check that setuid installs works (for < 5.11.0 only).
377XXX any other configs?
7277a900 378
f6af4394 379=item *
7277a900 380
f6af4394
DM
381Make sure you have a PAUSE account suitable for uploading a perl release.
382If you don't have a PAUSE account, then request one:
7277a900 383
f6af4394 384 https://pause.perl.org/pause/query?ACTION=request_id
7277a900 385
f6af4394
DM
386Check that your account is allowed to upload perl distros: goto
387https://pause.perl.org/, login, then select 'upload file to CPAN'; there
388should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas
389to add your ID to the list of people allowed to upload something called
390perl.
7277a900 391
f6af4394 392=item *
7277a900 393
f6af4394
DM
394Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if
395necessary, update the script to include new alias mappings.
7277a900 396
f6af4394
DM
397XXX This script is currently broken (7/2009). It needs updating to work
398with git and a lack of Changes files.
399
400=back
401
402=head2 Building a release candidate
403
404(At this point you should already have performed the actions described in
dc0a62a1
DM
405L</"Actions prior to the first release candidate">.) You should review
406that section to ensure that everything there has done, and to see whether
407any of those actions (such as consistency checks) need to be repeated.
f6af4394
DM
408
409=over 4
410
411=item *
412
413Re-read the perldelta to try to find any embarrassing typos and thinkos;
414remove any C<TODO> or C<XXX> flags; and run through pod and spell
636a1918
DM
415checkers, e.g.
416
417 podchecker -warnings -warnings pod/perl5101delta.pod
418 spell pod/perl5101delta.pod
f6af4394
DM
419
420=item *
421
422Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a
423final release, remove it. [ XXX how now?? see 34813 for old way ]
424
425=item *
426
427Update C<Module::Corelist>.
210de33e 428
ce4f4fe2 429Note that if this is a maint release, you should run the following actions
210de33e
DM
430from the maint directory, but edit the C<Corelist.pm> in I<blead> and
431subsequently cherry-pick it.
432
dc2f75c0
JV
433corelist.pl uses ftp.funet.fi to verify information about dual-lifed
434modules on CPAN. It can use a full, local CPAN mirror or fall back
435to C<wget> or C<curl> to fetch only package metadata remotely.
210de33e 436
dc2f75c0
JV
437(If you'd prefer to have a full CPAN mirror, see
438http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
210de33e 439
210de33e 440
dc2f75c0 441Then change to your perl checkout.
210de33e 442
dc2f75c0 443If you have a local CPAN mirror, run:
210de33e 444
dc2f75c0 445 $ perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
210de33e 446
dc2f75c0 447Otherwise, run:
210de33e 448
dc2f75c0 449 $ perl -Ilib Porting/corelist.pl cpan
210de33e 450
dc2f75c0
JV
451This will chug for a while. Assuming all goes well, it will
452 update lib/Module/CoreList.pm.
210de33e 453
dc2f75c0 454Check that file over carefully:
210de33e 455
dc2f75c0
JV
456 $ git diff lib/Module/CoreList.pm
457
458
459If necessary, bump C<$VERSION> (there's no need to do this for
460every RC; in RC1, bump the version to a new clean number that will
461appear in the final release, and leave as-is for the later RCs and final).
210de33e 462
ce4f4fe2 463Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
210de33e
DM
464entry, as that is likely to reflect the previous version number.
465
dc2f75c0
JV
466
467
210de33e
DM
468
469Add or update an entry to the C<%released> hash, including today's date
470(if this is just a release candidate, set the date to '????-??-??').
471
dc2f75c0
JV
472Finally, commit the new version of Module::CoreList:
473
474 $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \
475 lib/Module/Corelist.pm
476
7277a900 477
f6af4394
DM
478=item *
479
480Follow the instructions in the section L</"Building a snapshot">, then
481carry on with the extra steps that follow here.
482
483=item *
7277a900 484
addebd58
DM
485Disarm the patchlevel.h change [ XXX expand ]
486
487=item *
488
f6af4394
DM
489Wait for the smoke tests to catch up with the commit which this release is
490based on (or at least the last commit of any consequence).
7277a900 491
f6af4394
DM
492Then check that the smoke tests pass (particularly on Win32). If not, go
493back and fix things.
7277a900 494
7277a900 495
f6af4394 496=item *
7277a900 497
f6af4394 498Once smoking is okay, upload it to PAUSE. This is the point of no return.
addebd58 499You may wish to create a .bz2 version of the tarball and upload that too.
f6af4394 500
210de33e
DM
501=item *
502
503create a tag [XXX and branches and stuff ????], e.g.:
504
505 $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1'
506 $ git push origin tag perl-5.10.1-RC1
f6af4394
DM
507
508=item *
509
510Mail p5p to announce it, with a quote you prepared earlier.
511
512=item *
513
514Wait 24 hours or so, then post the announcement to use.perl.org.
addebd58
DM
515(if you don't have access rights to post news, ask someone like Rafael to
516do it for you.)
f6af4394
DM
517
518=back
519
520
521=head2 Making a final release
522
523At this point you should have a working release candidate with few or no
524changes since.
525
526It's essentially the same procedure as for making a release candidate, but
527with a whole bunch of extra post-release steps.
528
529=over 4
7277a900 530
f6af4394 531=item *
7277a900 532
f6af4394 533Follow the same steps as for making a release candidate, then
7277a900 534
f6af4394 535=item *
7277a900 536
f6af4394
DM
537Ask Jarkko to update http://www.cpan.org/src/README.html and
538Rafael to update http://dev.perl.org/perl5/
7277a900 539
f6af4394 540=item *
7277a900 541
f6af4394
DM
542Create a new empty perlNNNdelta.pod file for the current release + 1;
543see F<Porting/how_to_write_a_perldelta.pod>.
544[ XXX Perhaps we should have an empty template file we can copy in. ]
7277a900 545
a2cba4bc
NC
546In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous
547entry as 'D', then run C<perl pod/buildtoc --build-all> to update the
548following files:
7277a900 549
f6af4394 550 MANIFEST
f6af4394 551 pod/perl.pod
a2cba4bc
NC
552 win32/pod.mak
553 vms/descrip_mms.template
554
555(F<vms/descrip_mms.template> still needs a manual edit to bump the
556C<perldelta.pod> entry - it would be good for someone to figure out the fix.)
7277a900 557
f6af4394 558and change perlNNNdelta references to the new version in these files
7277a900 559
f6af4394
DM
560 INSTALL
561 win32/Makefile.mk
562 win32/Makefile
563 Makefile.SH
564 README
7277a900 565
f6af4394
DM
566Also, edit the previous delta file to change the C<NAME> from C<perldelta>
567to C<perlNNNdelta>.
7277a900 568
f6af4394
DM
569These two lists of files probably aren't exhaustive; do a recursive grep
570on the previous filename to look for suitable candidates.
7277a900 571
f6af4394 572(see 16410843ea for an example).
7277a900 573
f6af4394 574=item *
7277a900 575
dc0a62a1
DM
576If this was a maintenance release, then edit F<Porting/mergelog> to change
577all the C<d> (deferred) flags to C<.> (needs review).
578
579
580=item *
581
addebd58
DM
582If this was a major release, then
583
584=over
585
586=item *
587
588bump the version, e.g. 5.12.0 to 5.13.0;
589
590=item *
591
592[ XXX probably lots more stuff to do, including perldelta,
f6af4394 593C<lib/feature.pm> ]
7277a900 594
f6af4394 595=item *
7277a900 596
addebd58
DM
597Create a new maint branch with an empty Porting/mergelog file
598[ XXX and lots of other stuff too, probably ]
599
600=back
601
602=item *
603
f6af4394
DM
604Copy the perlNNNdelta.pod for this release into the other branches, and
605remember to update these files on those branches too:
7277a900 606
f6af4394
DM
607 MANIFEST
608 pod.lst
609 pod/perl.pod
610 vms/descrip_mms.template
611 win32/pod.mak
7277a900 612
f6af4394 613(see fc5be80860 for an example).
7277a900 614
f6af4394 615=item *
7277a900 616
f6af4394
DM
617Make sure any recent F<pod/perlhist.pod> entries are copied to
618F<perlhist.pod> on other branches; typically the RC* and final entries,
619e.g.
7277a900 620
f6af4394
DM
621 5.8.9-RC1 2008-Nov-10
622 5.8.9-RC2 2008-Dec-06
623 5.8.9 2008-Dec-14
7277a900 624
6e40fbf9
DM
625=item *
626
627Remind the current maintainer of C<Module::CoreList> to push a new release
628to CPAN.
629
7277a900
GS
630=back
631
632=head1 SOURCE
633
f6af4394
DM
634Based on
635http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
636plus a whole bunch of other sources, including private correspondence.
7277a900
GS
637
638=cut
639