add "get rt.perl permissions" to RMG
[perl.git] / Porting / release_managers_guide.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 release_managers_guide - Releasing a new version of perl 5.x
6
7 Note that things change at each release, so there may be new things not
8 covered here, or tools may need updating.
9
10 =head1 MAKING A CHECKLIST
11
12 If you are preparing to do a release, you can run the
13 F<Porting/make-rmg-checklist> script to generate a new version of this
14 document that starts with a checklist for your release.
15
16 This script is run as:
17
18   perl Porting/make-rmg-checklist \
19       --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod
20
21 You can also pass the C<--html> flag to generate an HTML document instead of
22 POD.
23
24   perl Porting/make-rmg-checklist --html \
25       --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html
26
27 =head1 SYNOPSIS
28
29 This document describes the series of tasks required - some automatic, some
30 manual - to produce a perl release of some description, be that a release
31 candidate, or final, numbered release of maint or blead.
32
33 The release process has traditionally been executed by the current
34 pumpking. Blead releases from 5.11.0 forward are made each month on the
35 20th by a non-pumpking release engineer.  The release engineer roster
36 and schedule can be found in Porting/release_schedule.pod.
37
38 This document both helps as a check-list for the release engineer 
39 and is a base for ideas on how the various tasks could be automated 
40 or distributed.
41
42 The checklist of a typical release cycle is as follows:
43
44     (5.10.1 is released, and post-release actions have been done)
45
46     ...time passes...
47
48     a few weeks before the release, a number of steps are performed,
49         including bumping the version to 5.10.2
50
51     ...a few weeks passes...
52
53     perl-5.10.2-RC1 is released
54
55     perl-5.10.2 is released
56
57     post-release actions are performed, including creating new
58         perldelta.pod
59
60     ... the cycle continues ...
61
62
63 =head1 DETAILS
64
65 Some of the tasks described below apply to all four types of
66 release of Perl. (blead, RC, final release of maint, final
67 release of blead). Some of these tasks apply only to a subset
68 of these release types.  If a step does not apply to a given 
69 type of release, you will see a notation to that effect at
70 the beginning of the step.
71
72
73 =head2 Release types
74
75 =over 4
76
77 =item Release Candidate (RC)
78
79 A release candidate is an attempt to produce a tarball that is a close as
80 possible to the final release. Indeed, unless critical faults are found
81 during the RC testing, the final release will be identical to the RC
82 barring a few minor fixups (updating the release date in F<perlhist.pod>,
83 removing the RC status from F<patchlevel.h>, etc). If faults are found,
84 then the fixes should be put into a new release candidate, never directly
85 into a final release.
86
87
88 =item Stable/Maint release (MAINT).
89
90 A release with an even version number, and subversion number > 0, such as
91 5.14.1 or 5.14.2.
92
93 At this point you should have a working release candidate with few or no
94 changes since.
95
96 It's essentially the same procedure as for making a release candidate, but
97 with a whole bunch of extra post-release steps.
98
99 =item A blead point release (BLEAD-POINT)
100
101 A release with an odd version number, such as 5.15.0 or 5.15.1.
102
103 This isn't for production, so it has less stability requirements than for
104 other release types, and isn't preceded by RC releases. Other than that,
105 it is similar to a MAINT release.
106
107 =item Blead final release (BLEAD-FINAL)
108
109 A release with an even version number, and subversion number == 0, such as
110 5.14.0. That is to say, it's the big new release once per year.
111
112 It's essentially the same procedure as for making a release candidate, but
113 with a whole bunch of extra post-release steps, even more than for MAINT.
114
115 =back
116
117 =for checklist begin
118
119 =head2 Prerequisites
120
121 Before you can make an official release of perl, there are a few
122 hoops you need to jump through:
123
124 =head3 PAUSE account with pumpkin status
125
126 Make sure you have a PAUSE account suitable for uploading a perl release.
127 If you don't have a PAUSE account, then request one:
128
129     https://pause.perl.org/pause/query?ACTION=request_id
130
131 Check that your account is allowed to upload perl distros: go to
132 L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that
133 your PAUSE ID is listed there.  If not, ask Andreas KE<0xf6>nig to add your ID
134 to the list of people allowed to upload something called perl.  You can find
135 Andreas' email address at:
136
137     https://pause.perl.org/pause/query?ACTION=pause_04imprint
138
139 =head3 search.cpan.org pumpkin status
140
141 Make sure that search.cpan.org knows that you're allowed to upload
142 perl distros. Contact Graham Barr to make sure that you're on the right
143 list.
144
145 =head3 rt.perl.org update access
146
147 Make sure you have permission to close tickets on L<http://rt.perl.org/>
148 so you can respond to bug report as necessary during your stint.  If you
149 don't, make an account (if you don't have one) and contact the pumpking
150 with your username to get ticket-closing permission.
151
152 =head3 git checkout and commit bit
153
154 You will need a working C<git> installation, checkout of the perl
155 git repository and perl commit bit.  For information about working
156 with perl and git, see F<pod/perlgit.pod>.
157
158 If you are not yet a perl committer, you won't be able to make a
159 release.  Have a chat with whichever evil perl porter tried to talk
160 you into the idea in the first place to figure out the best way to
161 resolve the issue.
162
163 =head3 git clone of https://github.com/perlorg/perlweb
164
165 For updating the L<http://dev.perl.org> web pages, either a Github account or
166 sweet-talking somebody with a Github account into obedience is needed. This
167 is only needed on the day of the release or shortly afterwards.
168
169 =for checklist skip RC
170
171 =head3 Quotation for release announcement epigraph
172
173 I<SKIP this step for RC>
174
175 For all except an RC release of perl, you will need a quotation
176 to use as an epigraph to your release announcement.
177
178 =head2 Building a release - advance actions
179
180 The work of building a release candidate for a numbered release of
181 perl generally starts several weeks before the first release candidate.
182 Some of the following steps should be done regularly, but all I<must> be
183 done in the run up to a release.
184
185 =head3 dual-life CPAN module synchronisation
186
187 Ensure that dual-life CPAN modules are synchronised with CPAN.  Basically,
188 run the following:
189
190     $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
191
192 to see any inconsistencies between the core and CPAN versions of distros,
193 then fix the core, or cajole CPAN authors as appropriate. See also the
194 C<-d> and C<-v> options for more detail.  You'll probably want to use the
195 C<-c cachedir> option to avoid repeated CPAN downloads and may want to
196 use C<-m file:///mirror/path> if you made a local CPAN mirror.
197
198 To see which core distro versions differ from the current CPAN versions:
199
200     $ ./perl -Ilib Porting/core-cpan-diff -x -a
201
202 If you are making a MAINT release, run C<core-cpan-diff> on both blead and
203 maint, then diff the two outputs. Compare this with what you expect, and if
204 necessary, fix things up. For example, you might think that both blead
205 and maint are synchronised with a particular CPAN module, but one might
206 have some extra changes. 
207
208
209 =head3 dual-life CPAN module stability
210
211 Ensure dual-life CPAN modules are stable, which comes down to:
212
213     for each module that fails its regression tests on $current
214         did it fail identically on $previous?
215         if yes, "SEP" (Somebody Else's Problem)
216         else work out why it failed (a bisect is useful for this)
217
218     attempt to group failure causes
219
220     for each failure cause
221         is that a regression?
222         if yes, figure out how to fix it
223             (more code? revert the code that broke it)
224         else
225             (presumably) it's relying on something un-or-under-documented
226             should the existing behaviour stay?
227                 yes - goto "regression"
228                 no - note it in perldelta as a significant bugfix
229                 (also, try to inform the module's author)
230
231
232 =head3 monitor smoke tests for failures
233
234 Similarly, monitor the smoking of core tests, and try to fix.  See
235 L<http://doc.procura.nl/smoke/index.html> for a summary. See also
236 L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has
237 the raw reports.
238
239 Similarly, monitor the smoking of perl for compiler warnings, and try to
240 fix.
241
242
243 =head3 update perldelta
244
245 Get perldelta in a mostly finished state.
246
247 Read  F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
248 every section it lists is, if necessary, populated and complete. Copy
249 edit the whole document.
250
251
252 =head3 Bump the version number
253
254 Increase the version number (e.g. from 5.12.0 to 5.12.1).
255
256 For a BLEAD-POINT release, this can happen on the day of the release.  For a
257 release candidate for a stable perl, this should happen a week or two
258 before the first release candidate to allow sufficient time for testing and
259 smoking with the target version built into the perl executable. For
260 subsequent release candidates and the final release, it it not necessary to
261 bump the version further.
262
263 There is a tool to semi-automate this process:
264
265      $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1
266
267 Remember that this tool is largely just grepping for '5.10.0' or whatever,
268 so it will generate false positives. Be careful not change text like
269 "this was fixed in 5.10.0"!
270
271 Use git status and git diff to select changes you want to keep.
272
273 Be particularly careful with F<INSTALL>, which contains a mixture of
274 C<5.10.0>-type strings, some of which need bumping on every release, and
275 some of which need to be left unchanged.
276 The line in F<INSTALL> about "is binary incompatible with" requires a
277 correct choice of earlier version to declare incompatibility with.
278
279 When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
280 C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
281 you're releasing, unless you're
282 absolutely sure the release you're about to make is 100% binary compatible
283 to an earlier release. When releasing a MAINT perl version, the C<PERL_API_*>
284 constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
285 in maint branches.
286
287 After editing, regenerate uconfig.h (this must be run on a system with a
288 /bin/sh available):
289
290     $ perl regen/uconfig_h.pl
291
292 Test your changes:
293
294     $ git clean -xdf   # careful if you don't have local files to keep!
295     $ ./Configure -des -Dusedevel
296     $ make
297     $ make test
298
299 Commit your changes:
300
301     $ git status
302     $ git diff
303     B<review the delta carefully>
304
305     $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
306
307 At this point you may want to compare the commit with a previous bump to
308 see if they look similar.  See commit 8891dd8d for an example of a
309 previous version bump.
310
311 When the version number is bumped, you should also update Module::CoreList
312 (as described below in L<"update Module::CoreList">) to reflect the new
313 version number.
314
315
316 =head3 update INSTALL
317
318 Review and update INSTALL to account for the change in version number;
319 in particular, the "Coexistence with earlier versions of perl 5" section.
320
321 Be particularly careful with the section "Upgrading from 5.X.Y or earlier".
322 The "X.Y" needs to be changed to the most recent version that we are
323 I<not> binary compatible with.
324
325 For MAINT and BLEAD-FINAL releases, this needs to refer to the last
326 release in the previous development cycle (so for example, for a 5.14.x
327 release, this would be 5.13.11).
328
329 For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
330 release (so for 5.15.3 this would be 5.15.2).
331
332 =head3 Check more build configurations
333
334 Check some more build configurations.
335
336     $ sh Configure -Dprefix=/tmp/perl-5.x.y  -Uinstallusrbinperl \
337         -Duseshrplib -Dusesitecustomize
338     $ make
339     $ make test
340
341 XXX think of other configurations that need testing.
342
343
344 =head3 update perlport
345
346 L<perlport> has a section currently named I<Supported Platforms> that
347 indicates which platforms are known to build in the current release.
348 If necessary update the list and the indicated version number.
349
350
351
352 =head2 Building a release - on the day
353
354 This section describes the actions required to make a release
355 that are performed on the actual day.
356
357
358 =head3 re-check earlier actions
359
360 Review all the actions in the previous section,
361 L<"Building a release - advance actions"> to ensure they are all done and
362 up-to-date.
363
364
365 =head3 bump version number
366
367 For a BLEAD-POINT release, if you did not bump the perl version number as
368 part of I<advance actions>, do that now.
369
370
371 =head3 finalize perldelta
372
373 Finalize the perldelta.  In particular, fill in the Acknowledgements
374 section, which can be generated with something like:
375
376   $ perl Porting/acknowledgements.pl v5.15.0..HEAD
377
378 Re-read the perldelta to try to find any embarrassing typos and thinkos;
379 remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
380 with any serious issues for which fixes are not going to happen now; and
381 run through pod and spell checkers, e.g.
382
383     $ podchecker -warnings -warnings pod/perldelta.pod
384     $ spell pod/perldelta.pod
385
386 Also, you may want to generate and view an HTML version of it to check
387 formatting, e.g.
388
389     $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html
390
391 Another good HTML preview option is http://search.cpan.org/pod2html
392
393 If you make changes, be sure to commit them.
394
395 =for checklist skip BLEAD-POINT MAINT RC
396
397 =head3 remove stale perldeltas
398
399 For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
400 from the BLEAD-POINT releases since the previous BLEAD_FINAL should have
401 now been consolidated into the current perldelta, and hence are now just
402 useless clutter.  They can be removed using:
403
404     $ git rm <file1> <file2> ...
405
406 For example, for RC0 of 5.16.0:
407
408     $ cd pod
409     $ git rm perldelta515*.pod
410
411 All mention to them should also be removed.  Edit F<pod/perl.pod> to remove
412 them from its table of contents, then run F<Porting/pod_rules.pl> to
413 propagate your changes there into all the other files that mention them
414 (including F<MANIFEST>). You'll need to C<git add> the files that it changes.
415
416 Then build a clean perl and do a full test
417
418     $ git status
419     $ git clean -dxf
420     $ ./Configure -Dusedevel -des
421     $ make
422     $ make test
423
424 Once all tests pass, commit your changes.
425
426 =head3 build a clean perl
427
428 If you skipped the previous step (removing the stale perldeltas)
429 make sure you have a gitwise-clean perl directory (no modified files,
430 unpushed commits etc):
431
432     $ git status
433     $ git clean -dxf
434
435 then configure and build perl so that you have a Makefile and porting tools:
436
437     $ ./Configure -Dusedevel -des && make
438
439 =head3 update Module::CoreList
440
441 Update C<Module::CoreList> with module version data for the new release.
442
443 Note that if this is a MAINT release, you should run the following actions
444 from the maint branch, but commit the C<CoreList.pm> changes in
445 I<blead> and subsequently cherry-pick any releases since the last
446 maint release and then your recent commit.  XXX need a better example
447
448 F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
449 modules on CPAN. It can use a full, local CPAN mirror or fall back
450 to C<wget> or C<curl> to fetch only package metadata remotely. (If you're
451 on Win32, then installing Cygwin is one way to have commands like C<wget>
452 and C<curl> available.)
453
454 (If you'd prefer to have a full CPAN mirror, see 
455 http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
456
457 Then change to your perl checkout, and if necessary,
458
459     $ make
460
461 If this is not the first update for this version (e.g. if it was updated
462 when the version number was originally bumped), first edit
463 F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
464 entries for this version from the C<%released> and C<%version> hashes:
465 they will have a key like C<5.010001> for 5.10.1.
466
467 XXX the edit-in-place functionality of Porting/corelist.pl should
468 be fixed to handle this automatically.
469
470 Then, If you have a local CPAN mirror, run:
471
472     $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
473
474 Otherwise, run:
475
476     $ ./perl -Ilib Porting/corelist.pl cpan
477
478 This will chug for a while, possibly reporting various warnings about
479 badly-indexed CPAN modules unrelated to the modules actually in core.
480 Assuming all goes well, it will update
481 F<dist/Module-CoreList/lib/Module/CoreList.pm>.
482
483 Check that file over carefully:
484
485     $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
486
487 =head4 Bump C<$Module::CoreList::VERSION>
488
489 If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for
490 every RC; in RC1, bump the version to a new clean number that will
491 appear in the final release, and leave as-is for the later RCs and final).
492 It may also happen that C<Module::CoreList> has been modified in blead, and
493 hence has a new version number already.  (But make sure it is not the same
494 number as a CPAN release.)
495
496 Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
497 entry, as that is likely to reflect the previous version number.
498
499 =head4 Bump version in Module::CoreList F<Changes>
500
501 Also edit Module::CoreList's new version number in its F<Changes>
502 file.
503
504 =head4 Add Module::CoreList version bump to perldelta
505
506 Add a perldelta entry for the new Module::CoreList version.
507
508 =for checklist skip RC
509
510 =head4 Update C<%Module::CoreList::released> and C<CAVEATS>
511
512 In addition, if this is a final release (rather than a release candidate):
513
514 =over 4 
515
516 =item *
517
518 Update this version's entry in the C<%released> hash with today's date.
519
520 =item *
521
522 Make sure that the script has correctly updated the C<CAVEATS> section
523
524 =back
525
526 =head4 Commit Module::CoreList changes
527
528 Finally, commit the new version of Module::CoreList:
529 (unless this is for MAINT; in which case commit it to blead first, then
530 cherry-pick it back).
531
532     $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
533
534 =for checklist skip RC
535
536 =head3 update perlhist.pod
537
538 I<You MUST SKIP this step for a RC release>
539
540 Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
541
542     David    5.10.1       2009-Aug-06
543
544 Make sure that the correct pumpking is listed in the left-hand column, and
545 if this is the first release under the stewardship of a new pumpking, make
546 sure that his or her name is listed in the section entitled
547 C<THE KEEPERS OF THE PUMPKIN>.
548
549 Be sure to commit your changes:
550
551     $ git commit -m 'add new release to perlhist' pod/perlhist.pod
552
553 =for checklist skip BLEAD-POINT
554
555 =head3 update patchlevel.h
556
557 I<You MUST SKIP this step for a BLEAD-POINT release>
558
559 Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
560 a final release, remove it. For example:
561
562      static const char * const local_patches[] = {
563              NULL
564     +        ,"RC1"
565              PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
566
567 Be sure to commit your change:
568
569     $ git commit -m 'bump version to RCnnn' patchlevel.h
570
571
572 =head3 build, test and check a fresh perl
573
574 Build perl, then make sure it passes its own test suite, and installs:
575
576     $ git clean -xdf
577     $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
578
579     # or if it's an odd-numbered version:
580     $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
581
582     $ make test install
583
584 Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
585 C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
586 especially as regards version numbers, patch and/or RC levels, and @INC
587 paths. Note that as they have been been built from a git working
588 directory, they will still identify themselves using git tags and
589 commits.
590
591 Then delete the temporary installation.
592
593
594 =head3 push the work so far
595
596 Push all your recent commits:
597
598     $ git push origin ....
599
600
601 =head3 tag the release
602
603 Tag the release (e.g.):
604
605     $ git tag v5.11.0 -m "First release of the v5.11 series!"
606
607 It is B<VERY> important that from this point forward, you not push
608 your git changes to the Perl master repository.  If anything goes
609 wrong before you publish your newly-created tag, you can delete
610 and recreate it.  Once you push your tag, we're stuck with it
611 and you'll need to use a new version number for your release.
612
613
614 =head3 build the tarball
615
616 Before you run the following, you might want to install 7-Zip (the
617 C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or
618 the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian,
619 or the C<advancecomp> port on macports - 7-Zip on Windows is the
620 same code as AdvanceCOMP, so Windows users get the smallest files
621 first time). These compress about 5% smaller than gzip and bzip2.
622 Over the lifetime of your distribution this will save a lot of
623 people a small amount of download time and disk space, which adds
624 up.
625
626 Create a tarball. Use the C<-s> option to specify a suitable suffix for
627 the tarball and directory name:
628
629     $ cd root/of/perl/tree
630     $ make distclean
631     $ git clean -xdf            # make sure perl and git agree on files
632     $ git status                # and there's nothing lying around
633
634     $ perl Porting/makerel -b -s RC1            # for a release candidate
635     $ perl Porting/makerel -b                   # for a final release
636
637 This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
638 the MANIFEST files into it, sets the correct permissions on them,
639 adds DOS line endings to some, then tars it up as
640 F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
641
642 If you're getting your tarball suffixed with -uncommitted and you're sure
643 your changes were all committed, you can override the suffix with:
644
645     $ perl Porting/makerel -b -s ''
646
647 XXX if we go for extra tags and branches stuff, then add the extra details
648 here
649
650 Finally, clean up the temporary directory, e.g.
651
652     $ rm -rf ../perl-x.y.z-RC1
653
654
655 =head3 test the tarball
656
657 Once you have a tarball it's time to test the tarball (not the repository).
658
659 =head4 Copy the tarball to a web server
660
661 Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
662 have access to.
663
664 =head4 Download the tarball to another machine
665
666 Download the tarball to some other machine. For a release candidate, 
667 you really want to test your tarball on two or more different platforms
668 and architectures. The #p5p IRC channel on irc.perl.org is a good place
669 to find willing victims.
670
671 =head4 Check that F<Configure> works
672
673 Check that basic configuration and tests work on each test machine:
674
675     $ ./Configure -des && make all test
676
677 =head4 Run the test harness and install
678
679 Check that the test harness and install work on each test machine:
680
681     $ make distclean
682     $ ./Configure -des -Dprefix=/install/path && make all test_harness install
683     $ cd /install/path
684
685 =head4 Check C<perl -v> and C<perl -V>
686
687 Check that the output of C<perl -v> and C<perl -V> are as expected,
688 especially as regards version numbers, patch and/or RC levels, and @INC
689 paths. 
690
691 Note that the results may be different without a F<.git/> directory,
692 which is why you should test from the tarball.
693
694 =head4 Run the Installation Verification Procedure utility
695
696     $ ./perl utils/perlivp
697     ...
698     All tests successful.
699     $
700
701 =head4 Compare the installed paths to the last release
702
703 Compare the pathnames of all installed files with those of the previous
704 release (i.e. against the last installed tarball on this branch which you
705 have previously verified using this same procedure). In particular, look
706 for files in the wrong place, or files no longer included which should be.
707 For example, suppose the about-to-be-released version is 5.10.1 and the
708 previous is 5.10.0:
709
710     cd installdir-5.10.0/
711     find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
712     cd installdir-5.10.1/
713     find . -type f | sort > /tmp/f2
714     diff -u /tmp/f[12]
715
716 =head4 Test the CPAN client
717
718 Bootstrap the CPAN client on the clean install:
719
720     $ bin/perl -MCPAN -e "shell"
721
722 If you're running this on Win32 you probably also need a set of Unix
723 command-line tools available for CPAN to function correctly without
724 Perl alternatives like LWP installed. Cygwin is an obvious choice.)
725
726 =head4 Install the Inline module and test it
727
728 Try installing a popular CPAN module that's reasonably complex and that
729 has dependencies; for example:
730
731     CPAN> install Inline
732     CPAN> quit
733
734 Check that your perl can run this:
735
736     $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
737     42
738     $
739
740 =head4 Bootstrap the CPANPLUS client
741
742 Bootstrap the CPANPLUS client on the clean install:
743
744     $ bin/cpanp
745
746 (Again, on Win32 you'll need something like Cygwin installed, but make sure
747 that you don't end up with its various F<bin/cpan*> programs being found on
748 the PATH before those of the Perl that you're trying to test.)
749
750 =head4 Install the DBI module with CPANPLUS
751
752     CPAN Terminal> i DBI
753     CPAN Terminal> quit
754     $ bin/perl -MDBI -e 1
755     $
756
757 =head4 Make sure that perlbug works
758
759 Test L<perlbug> with the following:
760
761     $ bin/perlbug
762     ...
763     Subject: test bug report
764     Local perl administrator [yourself]: 
765     Editor [vi]: 
766     Module: 
767     Category [core]: 
768     Severity [low]: 
769     (edit report)
770     Action (Send/Display/Edit/Subject/Save to File): f
771     Name of file to save message in [perlbug.rep]: 
772     Action (Send/Display/Edit/Subject/Save to File): q
773
774 and carefully examine the output (in F<perlbug.rep]>), especially
775 the "Locally applied patches" section. If everything appears okay, then
776 delete the file, and try it again, this time actually submitting the bug
777 report. Check that it shows up, then remember to close it!
778
779 =for checklist skip BLEAD-POINT
780
781 =head3 monitor smokes
782
783 Wait for the smoke tests to catch up with the commit which this release is
784 based on (or at least the last commit of any consequence).
785
786 Then check that the smoke tests pass (particularly on Win32). If not, go
787 back and fix things.
788
789 Note that for I<BLEAD-POINT> releases this may not be practical. It takes a
790 long time for the smokers to catch up, especially the Win32
791 smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL>
792 releases, but for I<BLEAD-POINT> releases sometimes the best you can do is
793 to plead with people on IRC to test stuff on their platforms, fire away,
794 and then hope for the best.
795
796
797 =head3 upload to PAUSE
798
799 Once smoking is okay, upload it to PAUSE. This is the point of no return.
800 If anything goes wrong after this point, you will need to re-prepare
801 a new release with a new minor version or RC number.
802
803     https://pause.perl.org/
804
805 (Login, then select 'Upload a file to CPAN')
806
807 If your workstation is not connected to a high-bandwidth,
808 high-reliability connection to the Internet, you should probably use the
809 "GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
810 new release from wherever you put it for testers to find it.  This will
811 eliminate anxious gnashing of teeth while you wait to see if your
812 15 megabyte HTTP upload successfully completes across your slow, twitchy
813 cable modem.  You can make use of your home directory on dromedary for
814 this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
815 F</home/USERNAME/public_html>, where F<USERNAME> is your login account
816 on dromedary.  I<Remember>: if your upload is partially successful, you
817 may need to contact a PAUSE administrator or even bump the version of perl.
818
819 Upload both the .gz and .bz2 versions of the tarball.
820
821 Do not proceed any further until you are sure that your tarballs are on
822 CPAN.  Check your authors directory on one of the "fast" CPAN mirrors
823 (e.g., cpan.hexten.net
824 or cpan.cpantesters.org) to confirm that your uploads have been successful.
825
826 =for checklist skip RC
827
828 =head3 wait for indexing
829
830 I<You MUST SKIP this step for RC>
831
832 Wait until you receive notification emails from the PAUSE indexer
833 confirming that your uploads have been received.  IMPORTANT -- you will
834 probably get an email that indexing has failed, due to module permissions.
835 This is considered normal.
836
837
838 =head3 publish tag
839
840 Now that you've shipped the new perl release to PAUSE, it's
841 time to publish the tag you created earlier to the public git repo (e.g.):
842
843     $ git push origin tag v5.11.0
844
845 =for checklist skip BLEAD-POINT
846
847 =head3 disarm patchlevel.h
848
849 I<You MUST SKIP this step for BLEAD-POINT release>
850
851 Disarm the F<patchlevel.h> change; for example,
852
853      static const char * const local_patches[] = {
854              NULL
855     -        ,"RC1"
856              PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
857
858 Be sure to commit your change:
859
860     $ git commit -m 'disarm RCnnn bump' patchlevel.h
861     $ git push origin ....
862
863
864
865 =head3 announce to p5p
866
867 Mail p5p to announce your new release, with a quote you prepared earlier.
868
869 Use the template at Porting/release_announcement_template.txt
870
871 =head3 update epigraphs.pod
872
873 Add your quote to F<Porting/epigraphs.pod> and commit it.
874 Your release announcement will probably not have reached the web-visible
875 archives yet, so you won't be able to include the customary link to the
876 release announcement yet.
877
878 =head3 blog about your epigraph
879
880 If you have a blog, please consider writing an entry in your blog explaining
881 why you chose that particular quote for your epigraph.
882
883 =for checklist skip RC
884
885 =head3 Module::CoreList nagging
886
887 I<You MUST SKIP this step for RC>
888
889 Remind the current maintainer of C<Module::CoreList> to push a new release
890 to CPAN.
891
892 =for checklist skip RC
893
894 =head3 new perldelta
895
896 I<You MUST SKIP this step for RC>
897
898 Create a new perldelta.
899
900 =over 4
901
902 =item *
903
904 Confirm that you have a clean checkout with no local changes.
905
906 =item *
907
908 Run F<Porting/new-perldelta.pl>
909
910 =item *
911
912 Run the C<git add> commands it outputs to add new and modified files.
913
914 =item *
915
916 Verify that the build still works, by running C<./Configure> and
917 C<make test_porting>. (On Win32, run C<nmake> and
918 C<nmake test TEST_FILES="porting\*.t ..\lib\diagnostics.t">.)
919
920 =item *
921
922 If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>,
923 run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail.
924 Skip to the end of its test output to see the options it offers you.
925
926 =item *
927
928 When C<make test_porting> passes, commit the new perldelta.
929
930 =back
931
932 At this point you may want to compare the commit with a previous bump to
933 see if they look similar.  See commit e3c71926d3 for an example of a
934 previous version bump.
935
936 =for checklist skip BLEAD-POINT MAINT RC
937
938 =head3 bump version
939
940 I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
941
942 If this was a BLEAD-FINAL release (i.e. the first release of a new maint
943 series, 5.x.0 where x is even), then bump the version in the blead branch
944 in git, e.g. 5.12.0 to 5.13.0.
945
946 First, add a new feature bundle to F<regen/feature.pl>, initially by just
947 copying the exiting entry, and bump the file's $VERSION (after the __END__
948 marker); e.g.
949
950          "5.14" => [qw(switch say state unicode_strings)],
951     +    "5.15" => [qw(switch say state unicode_strings)],
952
953 Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>.
954
955 Then follow the section L<"Bump the version number"> to bump the version
956 in the remaining files and test and commit.
957
958
959 =head3 clean build and test
960
961 Run a clean build and test to make sure nothing obvious is broken.
962
963 In particular, F<Porting/perldelta_template.pod> is intentionally exempted
964 from podchecker tests, to avoid false positives about placeholder text.
965 However, once it's copied to F<pod/perldelta.pod> the contents can now
966 cause test failures. Problems should resolved by doing one of the
967 following:
968
969 =over
970
971 =item 1
972
973 Replace placeholder text with correct text.
974
975 =item 2
976
977 If the problem is from a broken placeholder link, you can add it to the
978 array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>.  Lines
979 containing such links should be marked with C<XXX> so that they get
980 cleaned up before the next release.
981
982 =item 3
983
984 Following the instructions output by F<t/porting/podcheck.t> on how to
985 update its exceptions database.
986
987 =back
988
989 =head3 push commits
990
991 Finally, push any commits done above.
992
993     $ git push origin ....
994
995 =for checklist skip BLEAD-POINT MAINT RC
996
997 =head3 create maint branch
998
999 I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
1000
1001 If this was a BLEAD-FINAL release (i.e. the first release of a new maint
1002 series, 5.x.0 where x is even), then create a new maint branch based on
1003 the commit tagged as the current release.
1004
1005 Assuming you're using git 1.7.x or newer:
1006
1007     $ git checkout -b maint-5.12 v5.12.0
1008     $ git push origin -u maint-5.12
1009
1010
1011 =for checklist skip BLEAD-POINT MAINT RC
1012
1013 =head3 make the maint branch available in the APC
1014
1015 Clone the new branch into /srv/gitcommon/branches on camel so the APC will
1016 receive its changes.
1017
1018     $ git clone --branch maint-5.14 /gitroot/perl.git \
1019     ?  /srv/gitcommon/branches/perl-5.14.x
1020     $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x
1021
1022 And nag the sysadmins to make this directory available via rsync.
1023
1024 =for checklist skip BLEAD-POINT RC
1025
1026 =head3 copy perldelta.pod to other branches
1027
1028 I<You MUST SKIP this step for RC, BLEAD-POINT>
1029
1030 Copy the perldelta.pod for this release into the other branches; for
1031 example:
1032
1033     $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod    # for example
1034     $ git add pod/perl5101delta.pod
1035
1036 Edit F<pod/perl.pod> to add an entry for the file, e.g.:
1037
1038     perl5101delta               Perl changes in version 5.10.1
1039
1040 Then rebuild various files:
1041
1042     $ perl pod/buildtoc --build-all
1043
1044 Finally, commit:
1045
1046     $ git commit -a -m 'add perlXXXdelta'
1047
1048
1049 =head3 update perlhist.pod in other branches
1050
1051 Make sure any recent F<pod/perlhist.pod> entries are copied to
1052 F<perlhist.pod> on other branches
1053 e.g.
1054
1055           5.8.9         2008-Dec-14
1056
1057
1058 =head3 bump RT version number
1059
1060 Log into http://rt.perl.org/ and check whether the new version is in the RT
1061 fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is
1062 to go to L<https://rt.perl.org/rt3/Search/Build.html> and click on the drop
1063 downs next to the C<Perl Version> and C<Fixed In> labels.
1064
1065 If the new version is not listed there, send an email to C<perlbug-admin at
1066 perl.org> requesting this.
1067
1068 =head3 Relax!
1069
1070 I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
1071 much-needed rest and relaxation>.
1072
1073 Thanks for releasing perl!
1074
1075
1076 =head2 Building a release - the day after
1077
1078 =head3 link announcement in epigraphs.pod
1079
1080 Add, to your quote to F<Porting/epigraphs.pod>, a link to the release
1081 announcement in the web-visible mailing list archive.  Commit it.
1082
1083 =head3 check tarball availability
1084
1085 Check various website entries to make sure the that tarball has appeared
1086 and is properly indexed:
1087
1088 =over 4
1089
1090 =item *
1091
1092 Check your author directory under L<http://www.cpan.org/authors/id/>
1093 to ensure that the tarballs are available on the website.
1094
1095 =item *
1096
1097 Check C</src> on CPAN (on a fast mirror) to ensure that links to
1098 the new tarballs have appeared.  There should be links in C</src/5.0>
1099 (which is accumulating all new versions), links in C</src> (which shows
1100 only the latest version on each branch), and an appropriate mention in
1101 C</src/README.html> (which describes the latest versions).
1102
1103 These links should appear automatically, some hours after upload.
1104 If they don't, or the C<README.html> description is inadequate,
1105 ask Ask <ask@perl.org>.
1106
1107 =item *
1108
1109 Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
1110 have been correctly mirrored to the website.
1111 If they haven't, ask Ask <ask@perl.org>.
1112
1113 =item *
1114
1115 Check L<http://search.cpan.org> to see if it has indexed the distribution.
1116 It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
1117
1118 =back
1119
1120 =for checklist skip RC
1121
1122 =head3 update dev.perl.org
1123
1124 I<You MUST SKIP this step for a RC release>
1125
1126 In the C<perlorg> repository, edit F<docs/dev/perl5/index.html>
1127 to link to this new release. Then make a pull request to Leo Lapworth.
1128 If this fails for some reason and you cannot cajole anybody else into
1129 submitting that change, you can mail Leo as last resort.
1130
1131 =for checklist end
1132
1133 =head1 SOURCE
1134
1135 Based on
1136 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
1137 plus a whole bunch of other sources, including private correspondence.
1138
1139 =cut
1140