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