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