This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
a18c4a590382f235037bd917d40865ec7f869e99
[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 outline 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
102 =head2 Prerequisites
103
104 Before you can make an official release of perl, there are a few
105 hoops you need to jump through:
106
107 =over 4
108
109 =item PAUSE account
110
111 Make sure you have a PAUSE account suitable for uploading a perl release.
112 If you don't have a PAUSE account, then request one:
113
114     https://pause.perl.org/pause/query?ACTION=request_id
115
116 Check that your account is allowed to upload perl distros: go to
117 L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that
118 your PAUSE ID is listed there.  If not, ask Andreas KE<0xf6>nig to add your ID
119 to the list of people allowed to upload something called perl.  You can find
120 Andreas' email address at:
121
122     https://pause.perl.org/pause/query?ACTION=pause_04imprint
123
124 =item search.cpan.org
125
126 Make sure that search.cpan.org knows that you're allowed to upload
127 perl distros. Contact Graham Barr to make sure that you're on the right
128 list.
129
130 =item CPAN mirror
131
132 Some release engineering steps require a full mirror of the CPAN.
133 Work to fall back to using a remote mirror via HTTP is incomplete
134 but ongoing. (No, a minicpan mirror is not sufficient)
135
136 =item git checkout and commit bit
137
138 You will need a working C<git> installation, checkout of the perl
139 git repository and perl commit bit.  For information about working
140 with perl and git, see F<pod/perlgit.pod>.
141
142 If you are not yet a perl committer, you won't be able to make a
143 release.  Have a chat with whichever evil perl porter tried to talk
144 you into the idea in the first place to figure out the best way to
145 resolve the issue.
146
147
148 =item 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
156 =back
157
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. It works in two stages.
246 First, it generates a list of suggested changes, which you review and
247 edit; then you feed this list back and it applies the edits. So, first
248 scan the source directory looking for likely candidates. The command line
249 arguments are the old and new version numbers, and -s means scan:
250
251     $ ./perl -Ilib Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan
252
253 This produces a file containing a list of suggested edits, e.g.:
254
255     NetWare/Makefile
256
257        89: -MODULE_DESC     = "Perl 5.10.0 for NetWare"
258            +MODULE_DESC     = "Perl 5.10.1 for NetWare"
259
260 i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown.
261 Review the file carefully, and delete any -/+ line pairs that you don't
262 want changing. You can also edit just the C<+> line to change the
263 suggested replacement text. Remember that this tool is largely just
264 grepping for '5.10.0' or whatever, so it will generate false positives. Be
265 careful not change text like "this was fixed in 5.10.0"! Then run:
266
267     $ ./perl -Ilib Porting/bump-perl-version -u < /tmp/scan
268
269 which will update all the files shown.
270
271 Instead of these two steps, bump-perl-version can also make these changes
272 inplace in one step, and you can use git status and git diff to select
273 changes you want to keep:
274
275      $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1
276
277 Be particularly careful with F<INSTALL>, which contains a mixture of
278 C<5.10.0>-type strings, some of which need bumping on every release, and
279 some of which need to be left unchanged.
280 The line in F<INSTALL> about "is binary incompatible with" requires a
281 correct choice of earlier version to declare incompatibility with.
282
283 Also note that this tool
284 currently only detects a single substitution per line: so in particular,
285 this line in README.vms needs special handling:
286
287     rename perl-5^.10^.1.dir perl-5_10_1.dir
288
289 When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
290 C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
291 you're releasing, unless you're
292 absolutely sure the release you're about to make is 100% binary compatible
293 to an earlier release. When releasing a MAINT perl version, the C<PERL_API_*>
294 constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
295 in maint branches.
296
297 After editing, regenerate uconfig.h (this must be run on a system with a
298 /bin/sh available):
299
300     $ perl regen/uconfig_h.pl
301
302 Test your changes:
303
304     $ git clean -xdf   # careful if you don't have local files to keep!
305     $ ./Configure -des -Dusedevel
306     $ make
307     $ make test
308
309 Commit your changes:
310
311     $ git st
312     $ git diff
313     B<review the delta carefully>
314
315     $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
316
317 At this point you may want to compare the commit with a previous bump to
318 see if they look similar.  See commit 8891dd8d for an example of a
319 previous version bump.
320
321 When the version number is bumped, you should also update Module::CoreList
322 (as described below in L<"update Module::CoreList">) to reflect the new
323 version number.
324
325
326 =head3 update INSTALL
327
328 Review and update INSTALL to account for the change in version number;
329 in particular, the "Coexistence with earlier versions of perl 5" section.
330
331 Be particularly careful with the section "Upgrading from 5.X.Y or earlier".
332 The "X.Y" needs to be changed to the most recent version that we are
333 I<not> binary compatible with.
334
335 For MAINT and BLEAD-FINAL releases, this needs to refer to the last
336 release in the previous development cycle (so for example, for a 5.14.x
337 release, this would be 5.13.11).
338
339 For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
340 release (so for 5.15.3 this would be 5.15.2).
341
342 =head3 Check more build configurations
343
344 Check some more build configurations. The check that setuid builds and
345 installs is for < 5.11.0 only.
346
347     $ sh Configure -Dprefix=/tmp/perl-5.x.y  -Uinstallusrbinperl \
348         -Duseshrplib -Dd_dosuid
349     $ make
350     $ LD_LIBRARY_PATH=`pwd` make test     # or similar for useshrplib
351
352     $ make suidperl
353     $ su -c 'make install'
354     $ ls -l .../bin/sperl
355     -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl
356
357 (Then delete the installation directory.)
358
359 XXX think of other configurations that need testing.
360
361
362 =head3 update perlport
363
364 L<perlport> has a section currently named I<Supported Platforms> that
365 indicates which platforms are known to build in the current release.
366 If necessary update the list and the indicated version number.
367
368
369
370 =head2 Building a release - on the day
371
372 This section describes the actions required to make a release
373 that are performed on the actual day.
374
375
376 =head3 re-check earlier actions
377
378 Review all the actions in the previous section,
379 L<"Building a release - advance actions"> to ensure they are all done and
380 up-to-date.
381
382
383 =head3 bump version number
384
385 For a BLEAD-POINT release, if you did not bump the perl version number as
386 part of I<advance actions>, do that now.
387
388
389 =head3 finalize perldelta
390
391 Finalize the perldelta.  In particular, fill in the Acknowledgements
392 section.  You can generate a list of contributors with checkAUTHORS.pl.
393 For example:
394
395   $ git log --pretty=fuller v5.13.${last}..HEAD | \
396     perl Porting/checkAUTHORS.pl --who -
397
398 Look at the previous L<perldelta> for how to write the opening
399 paragraph of the Acknowledgements section. To get the amount of
400 changed files and number of lines use this command:
401
402   $ git diff --shortstat v5.13.${last}..HEAD | \
403     ./perl -Ilib -nE 'my ($files, $insert, $delete) = /(\d+)/ga; say "$files files and ", $insert + $delete, " lines changed"'
404
405 Making sure to round off the number of lines changed.
406
407 Re-read the perldelta to try to find any embarrassing typos and thinkos;
408 remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
409 with any serious issues for which fixes are not going to happen now; and
410 run through pod and spell checkers, e.g.
411
412     $ podchecker -warnings -warnings pod/perldelta.pod
413     $ spell pod/perldelta.pod
414
415 Also, you may want to generate and view an HTML version of it to check
416 formatting, e.g.
417
418     $ ./perl -Ilib ext/Pod-Html/pod2html pod/perldelta.pod > /tmp/perldelta.html
419
420 Another good HTML preview option is http://search.cpan.org/pod2html
421
422 If you make changes, be sure to commit them.
423
424
425 =head3 build a clean perl
426
427 Make sure you have a gitwise-clean perl directory (no modified files,
428 unpushed commits etc):
429
430     $ git status
431     $ git clean -dxf
432
433 then configure and build perl so that you have a Makefile and porting tools:
434
435     $ ./Configure -Dusedevel -des && make
436
437
438 =head3 update Module::CoreList
439
440 Update C<Module::CoreList> with module version data for the new release.
441
442 Note that if this is a MAINT release, you should run the following actions
443 from the maint branch, but commit the C<CoreList.pm> changes in
444 I<blead> and subsequently cherry-pick any releases since the last
445 maint release and then your recent commit.  XXX need a better example
446
447 F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
448 modules on CPAN. It can use a full, local CPAN mirror or fall back
449 to C<wget> or C<curl> to fetch only package metadata remotely. (If you're
450 on Win32, then installing Cygwin is one way to have commands like C<wget>
451 and C<curl> available.)
452
453 (If you'd prefer to have a full CPAN mirror, see 
454 http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
455
456 Then change to your perl checkout, and if necessary,
457
458     $ make
459
460 If this not the first update for this version (e.g. if it was updated
461 when the version number was originally bumped), first edit
462 F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
463 entries for this version from the C<%released> and C<%version> hashes:
464 they will have a key like C<5.010001> for 5.10.1.
465
466 XXX the edit-in-place functionality of Porting/corelist.pl should
467 be fixed to handle this automatically.
468
469 Then, If you have a local CPAN mirror, run:
470
471     $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
472
473 Otherwise, run:
474
475     $ ./perl -Ilib Porting/corelist.pl cpan
476
477 This will chug for a while, possibly reporting various warnings about
478 badly-indexed CPAN modules unrelated to the modules actually in core.
479 Assuming all goes well, it will update
480 F<dist/Module-CoreList/lib/Module/CoreList.pm>.
481
482 Check that file over carefully:
483
484     $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
485
486 If necessary, bump C<$VERSION> (there's no need to do this for
487 every RC; in RC1, bump the version to a new clean number that will
488 appear in the final release, and leave as-is for the later RCs and final).
489
490 Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
491 entry, as that is likely to reflect the previous version number.
492
493 Also edit Module::CoreList's new version number in its F<Changes>
494 file.
495
496 Add a perldelta entry for the new Module::CoreList version.
497
498 You should also add the version you're about to release to the
499 L<Module::CoreList/CAVEATS> section which enumerates the perl releases
500 that Module::CoreList covers.
501
502 In addition, if this is a final release (rather than a release candidate):
503
504 =over 4 
505
506 =item *
507
508 Update this version's entry in the C<%released> hash with today's date.
509
510 =item *
511
512 Make sure that the script has correctly updated the C<CAVEATS> section
513
514 =back
515
516 Finally, commit the new version of Module::CoreList:
517 (unless this is for MAINT; in which case commit it to blead first, then
518 cherry-pick it back).
519
520     $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
521
522
523 =head3 check MANIFEST
524
525 Check that the manifest is sorted and correct:
526
527     $ make distclean
528     $ git clean -xdf # This shouldn't be necessary if distclean is correct
529     $ perl Porting/manicheck
530
531 If manicheck turns up anything wrong, update MANIFEST and begin this step again.
532
533     $ ./configure -des -Dusedevel
534     $ make test_porting
535     $ git commit -m 'Update MANIFEST' MANIFEST
536
537
538 =head3 update perlhist.pod
539
540 I<You MUST SKIP this step for a RC release>
541
542 Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
543
544     David    5.10.1       2009-Aug-06
545
546 Make sure that the correct pumpking is listed in the left-hand column, and
547 if this is the first release under the stewardship of a new pumpking, make
548 sure that his or her name is listed in the section entitled
549 C<THE KEEPERS OF THE PUMPKIN>.
550
551 Be sure to commit your changes:
552
553     $ git commit -m 'add new release to perlhist' pod/perlhist.pod
554
555
556 =head3 update patchlevel.h
557
558 I<You MUST SKIP this step for a BLEAD-POINT release>
559
560 Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
561 a final release, remove it. For example:
562
563      static const char * const local_patches[] = {
564              NULL
565     +        ,"RC1"
566              PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
567
568 Be sure to commit your change:
569
570     $ git commit -m 'bump version to RCnnn' patchlevel.h
571
572
573 =head3 build, test and check a fresh perl
574
575 Build perl, then make sure it passes its own test suite, and installs:
576
577     $ git clean -xdf
578     $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
579
580     # or if it's an odd-numbered version:
581     $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
582
583     $ make test install
584
585 Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
586 C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
587 especially as regards version numbers, patch and/or RC levels, and @INC
588 paths. Note that as they have been been built from a git working
589 directory, they will still identify themselves using git tags and
590 commits.
591
592 Then delete the temporary installation.
593
594
595 =head3 push the work so far
596
597 Push all your recent commits:
598
599     $ git push origin ....
600
601
602 =head3 tag the release
603
604 Tag the release (e.g.):
605
606     $ git tag v5.11.0 -m "First release of the v5.11 series!"
607
608 It is B<VERY> important that from this point forward, you not push
609 your git changes to the Perl master repository.  If anything goes
610 wrong before you publish your newly-created tag, you can delete
611 and recreate it.  Once you push your tag, we're stuck with it
612 and you'll need to use a new version number for your release.
613
614
615 =head3 build the tarball
616
617 Create a tarball. Use the C<-s> option to specify a suitable suffix for
618 the tarball and directory name:
619
620     $ cd root/of/perl/tree
621     $ make distclean
622     $ git clean -xdf            # make sure perl and git agree on files
623     $ git status                # and there's nothing lying around
624
625     $ perl Porting/makerel -b -s RC1            # for a release candidate
626     $ perl Porting/makerel -b                   # for a final release
627
628 This creates the  directory F<../perl-x.y.z-RC1> or similar, copies all
629 the MANIFEST files into it, sets the correct permissions on them,
630 adds DOS line endings to some, then tars it up as
631 F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
632
633 If you're getting your tarball suffixed with -uncommitted and you're sure
634 your changes were all committed, you can override the suffix with:
635
636     $ perl Porting/makerel -b -s ''
637
638 XXX if we go for extra tags and branches stuff, then add the extra details
639 here
640
641 Optionally, you might want to compress your tarball more. Unix F<gzip>
642 doesn't actually produce the smallest possible DEFLATE output. If you have the
643 AdvanceCOMP suite (e.g. the C<advancecomp> port on macports), you can run
644
645     $ advdef -z -4 ../perl-x.y.z-RC1.tar.gz
646
647 which will probably shrink your tarball by about 5%. Over the lifetime of
648 your distribution this will save a lot of people a small amount of download
649 time and disk space, which adds up.
650
651 (7-Zip on Windows is the same code as AdvanceCOMP, so Windows users get the
652 smallest files first time)
653
654
655 Finally, clean up the temporary directory, e.g.
656
657     $ rm -rf ../perl-x.y.z-RC1
658
659
660 =head3 test the tarball
661
662 =over 4
663
664 =item *
665
666 Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
667 have access to.
668
669 =item *
670
671 Download the tarball to some other machine. For a release candidate, 
672 you really want to test your tarball on two or more different platforms
673 and architectures. The #p5p IRC channel on irc.perl.org is a good place
674 to find willing victims.
675
676 =item *
677
678 Check that basic configuration and tests work on each test machine:
679
680     $ ./Configure -des && make all test
681
682 =item *
683
684 Check that the test harness and install work on each test machine:
685
686     $ make distclean
687     $ ./Configure -des -Dprefix=/install/path && make all test_harness install
688     $ cd /install/path
689
690 =item *
691
692 Check that the output of C<perl -v> and C<perl -V> are as expected,
693 especially as regards version numbers, patch and/or RC levels, and @INC
694 paths. 
695
696 Note that the results may be different without a F<.git/> directory,
697 which is why you should test from the tarball.
698
699 =item *
700
701 Run the Installation Verification Procedure utility:
702
703     $ ./perl utils/perlivp
704     ...
705     All tests successful.
706     $
707
708 =item *
709
710 Compare the pathnames of all installed files with those of the previous
711 release (i.e. against the last installed tarball on this branch which you
712 have previously verified using this same procedure). In particular, look
713 for files in the wrong place, or files no longer included which should be.
714 For example, suppose the about-to-be-released version is 5.10.1 and the
715 previous is 5.10.0:
716
717     cd installdir-5.10.0/
718     find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
719     cd installdir-5.10.1/
720     find . -type f | sort > /tmp/f2
721     diff -u /tmp/f[12]
722
723 =item *
724
725 Bootstrap the CPAN client on the clean install:
726
727     $ bin/perl -MCPAN -e "shell"
728
729 If you're running this on Win32 you probably also need a set of Unix
730 command-line tools available for CPAN to function correctly without
731 Perl alternatives like LWP installed. Cygwin is an obvious choice.)
732
733 =item *
734
735 Try installing a popular CPAN module that's reasonably complex and that
736 has dependencies; for example:
737
738     CPAN> install Inline
739     CPAN> quit
740
741 Check that your perl can run this:
742
743     $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
744     42
745     $
746
747 =item *
748
749 Bootstrap the CPANPLUS client on the clean install:
750
751     $ bin/cpanp
752
753 (Again, on Win32 you'll need something like Cygwin installed, but make sure
754 that you don't end up with its various F<bin/cpan*> programs being found on
755 the PATH before those of the Perl that you're trying to test.)
756
757 =item *
758
759 Install an XS module, for example:
760
761     CPAN Terminal> i DBI
762     CPAN Terminal> quit
763     $ bin/perl -MDBI -e 1
764     $
765
766 =item *
767
768 Check that the L<perlbug> utility works. Try the following:
769
770     $ bin/perlbug
771     ...
772     Subject: test bug report
773     Local perl administrator [yourself]: 
774     Editor [vi]: 
775     Module: 
776     Category [core]: 
777     Severity [low]: 
778     (edit report)
779     Action (Send/Display/Edit/Subject/Save to File): f
780     Name of file to save message in [perlbug.rep]: 
781     Action (Send/Display/Edit/Subject/Save to File): q
782
783 and carefully examine the output (in F<perlbug.rep]>), especially
784 the "Locally applied patches" section. If everything appears okay, then
785 delete the file, and try it again, this time actually submitting the bug
786 report. Check that it shows up, then remember to close it!
787
788 =back
789
790
791 =head3 monitor smokes
792
793 Wait for the smoke tests to catch up with the commit which this release is
794 based on (or at least the last commit of any consequence).
795
796 Then check that the smoke tests pass (particularly on Win32). If not, go
797 back and fix things.
798
799 Note that for I<BLEAD-POINT> releases this may not be practical. It takes a
800 long time for the smokers to catch up, especially the Win32
801 smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL>
802 releases, but for I<BLEAD-POINT> releases sometimes the best you can do is
803 to plead with people on IRC to test stuff on their platforms, fire away,
804 and then hope for the best.
805
806
807 =head3 upload to PAUSE
808
809 Once smoking is okay, upload it to PAUSE. This is the point of no return.
810 If anything goes wrong after this point, you will need to re-prepare
811 a new release with a new minor version or RC number.
812
813     https://pause.perl.org/
814
815 (Login, then select 'Upload a file to CPAN')
816
817 If your workstation is not connected to a high-bandwidth,
818 high-reliability connection to the Internet, you should probably use the
819 "GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
820 new release from wherever you put it for testers to find it.  This will
821 eliminate anxious gnashing of teeth while you wait to see if your
822 15 megabyte HTTP upload successfully completes across your slow, twitchy
823 cable modem.  You can make use of your home directory on dromedary for
824 this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
825 F</home/USERNAME/public_html>, where F<USERNAME> is your login account
826 on dromedary.  I<Remember>: if your upload is partially successful, you
827 may need to contact a PAUSE administrator or even bump the version of perl.
828
829 Upload both the .gz and .bz2 versions of the tarball.
830
831 Wait until you receive notification emails from the PAUSE indexer
832 confirming that your uploads have been received.  IMPORTANT -- you will
833 probably get an email that indexing has failed, due to module permissions.
834 This is considered normal.
835
836 Do not proceed any further until you are sure that your tarballs are on
837 CPAN.  Check your authors directory on one of the "fast" CPAN mirrors
838 (e.g., cpan.hexten.net
839 or cpan.cpantesters.org) to confirm that your uploads have been successful.
840
841
842 =head3 publish tag
843
844 Now that you've shipped the new perl release to PAUSE, it's
845 time to publish the tag you created earlier to the public git repo (e.g.):
846
847     $ git push origin tag v5.11.0
848
849
850 =head3 disarm patchlevel.h
851
852 I<You MUST SKIP this step for BLEAD-POINT release>
853
854 Disarm the F<patchlevel.h> change; for example,
855
856      static const char * const local_patches[] = {
857              NULL
858     -        ,"RC1"
859              PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
860
861 Be sure to commit your change:
862
863     $ git commit -m 'disarm RCnnn bump' patchlevel.h
864     $ git push origin ....
865
866
867
868 =head3 announce to p5p
869
870 Mail p5p to announce your new release, with a quote you prepared earlier.
871
872
873 =head3 update epigraphs.pod
874
875 Add your quote to F<Porting/epigraphs.pod> and commit it.
876
877
878 =head3 Module::CoreList nagging
879
880 I<You MUST SKIP this step for RC>
881
882 Remind the current maintainer of C<Module::CoreList> to push a new release
883 to CPAN.
884
885
886 =head3 new perldelta
887
888 I<You MUST SKIP this step for RC>
889
890 Create a new perldelta.
891
892 B<Note>: currently, the buildtoc below must be run in a I<built> perl source
893 directory, as at least one of the pod files it expects to find is
894 autogenerated: perluniprops.pod. But you can't build perl if you've added
895 the new perldelta file and not updated toc. So, make sure you have a built
896 perl (with a pod/perluniprops.pod file) now, I<before> continuing.
897
898 First, update the F<pod/.gitignore> file  to ignore the next
899 release's generated F<pod/perlNNNdelta.pod> file rather than this release's
900 one which we are about to set in stone (where NNN is the perl version number
901 without the dots. i.e. 5135 for 5.13.5).
902
903     $ (edit pod/.gitignore )
904     $ git add pod/.gitignore
905
906 Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>,
907 and edit the moved delta file to change the C<NAME> from C<perldelta> to
908 C<perlNNNdelta>.  For example, assuming you just released 5.10.1, and are
909 about to create the 5.10.2 perldelta:
910
911     $ rm  pod/perl5101delta.pod # remove the auto-generated file, if any
912     $ git mv pod/perldelta.pod pod/perl5101delta.pod
913     $ (edit pod/perl5101delta.pod to retitle)
914     $ git add pod/perl5101delta.pod
915
916 Then create a new empty perldelta.pod file for the new release; see
917 F<Porting/how_to_write_a_perldelta.pod>. You should be able to do this by
918 just copying in a skeleton template and then doing a quick fix up of the
919 version numbers.  Then commit the move and the new file.
920
921     $ cp -i Porting/perldelta_template.pod pod/perldelta.pod
922     $ (edit pod/perldelta.pod)
923     $ git add pod/perldelta.pod
924     $ git commit -m 'create perldelta for 5.10.2'
925
926 =head3 update perldelta TOC and references
927
928 Now you need to update various tables of contents related to perldelta,
929 most of which can be generated automatically.
930
931 Edit F<pod.lst>: add the new entry for the perlNNNdelta file for the
932 current version (the file that will be symlinked to perldelta).
933
934 Manually create a temporary link to the new delta file; normally this is
935 done from the Makefile, but the Makefile is updated by buildtoc, and
936 buildtoc won't run without the file there:
937
938     $ ln -s perldelta.pod pod/perl5102delta.pod
939
940 Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
941 the following files:
942
943     MANIFEST
944     Makefile.SH
945     pod/perl.pod
946     vms/descrip_mms.template
947     win32/Makefile
948     win32/makefile.mk
949     win32/pod.mak
950
951 Finally, commit:
952
953     $ git commit -a -m 'update TOC for perlNNNdelta'
954
955 At this point you may want to compare the commit with a previous bump to
956 see if they look similar.  See commit dd885b5 for an example of a
957 previous version bump.
958
959
960 =head3 bump version
961
962 I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
963
964 If this was a BLEAD-FINAL release (i.e. the first release of a new maint
965 series, 5.x.0 where x is even), then bump the version in the blead branch
966 in git, e.g. 5.12.0 to 5.13.0.
967
968 First, add a new feature bundle to F<lib/feature.pm>, initially by just
969 copying the exiting entry, and bump the file's $VERSION; e.g.
970
971          "5.14" => [qw(switch say state unicode_strings)],
972     +    "5.15" => [qw(switch say state unicode_strings)],
973
974 Then follow the section L<"Bump the version number"> to bump the version
975 in the remaining files and test and commit.
976
977
978 =head3 push commits
979
980 Finally, push any commits done above.
981
982     $ git push origin ....
983
984
985 =head3 create maint branch
986
987 I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
988
989 If this was a BLEAD-FINAL release (i.e. the first release of a new maint
990 series, 5.x.0 where x is even), then create a new maint branch based on
991 the commit tagged as the current release.
992
993 Assuming you're using git 1.7.x or newer:
994
995     $ git checkout -b maint-5.12 v5.12.0
996     $ git push origin -u maint-5.12
997
998
999 =head3 make the maint branch available in the APC
1000
1001 Clone the new branch into /srv/gitcommon/branches on camel so the APC will
1002 receive its changes.
1003
1004     $ git clone --branch maint-5.14 /gitroot/perl.git \
1005     ?  /srv/gitcommon/branches/perl-5.14.x
1006     $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x
1007
1008 And nag the sysadmins to make this directory available via rsync.
1009
1010
1011 =head3 copy perldelta.pod to other branches
1012
1013 I<You MUST SKIP this step for RC, BLEAD-POINT>
1014
1015 Copy the perldelta.pod for this release into the other branches; for
1016 example:
1017
1018     $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod    # for example
1019     $ git add pod/perl5101delta.pod
1020
1021 Edit F<pod.lst> to add an entry for the file, e.g.:
1022
1023     perl5101delta               Perl changes in version 5.10.1
1024
1025 Then rebuild various files:
1026
1027     $ perl pod/buildtoc --build-all
1028
1029 Finally, commit:
1030
1031     $ git commit -a -m 'add perlXXXdelta'
1032
1033
1034 =head3 update perlhist.pod in other branches
1035
1036 Make sure any recent F<pod/perlhist.pod> entries are copied to
1037 F<perlhist.pod> on other branches
1038 e.g.
1039
1040           5.8.9         2008-Dec-14
1041
1042
1043 =head3 bump RT version number
1044
1045 Log into http://rt.perl.org/ and check whether the new version is
1046 in the RT fields C<Perl Version> and C<Fixed In>. If not, send an
1047 email to C<perlbug-admin at perl.org> requesting this.
1048
1049 =head3 Relax!
1050
1051 I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
1052 much-needed rest and relaxation>.
1053
1054 Thanks for releasing perl!
1055
1056
1057 =head2 Building a release - the day after
1058
1059 =head3 check tarball availability
1060
1061 Check various website entries to make sure the that tarball has appeared
1062 and is properly indexed:
1063
1064 =over 4
1065
1066 =item *
1067
1068 Check your author directory under L<http://www.cpan.org/authors/id/>
1069 to ensure that the tarballs are available on the website.
1070
1071 =item *
1072
1073 Check C</src> on CPAN (on a fast mirror) to ensure that links to
1074 the new tarballs have appeared.  There should be links in C</src/5.0>
1075 (which is accumulating all new versions), links in C</src> (which shows
1076 only the latest version on each branch), and an appropriate mention in
1077 C</src/README.html> (which describes the latest versions).
1078
1079 These links should appear automatically, some hours after upload.
1080 If they don't, or the C<README.html> description is inadequate,
1081 ask Ask <ask@perl.org>.
1082
1083 =item *
1084
1085 Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
1086 have been correctly mirrored to the website.
1087 If they haven't, ask Ask <ask@perl.org>.
1088
1089 =item *
1090
1091 Check L<http://search.cpan.org> to see if it has indexed the distribution.
1092 It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
1093
1094 =back
1095
1096
1097 =head3 update dev.perl.org
1098
1099 I<This step ONLY for BLEAD-POINT and MAINT>
1100
1101 Ask Leo Lapworth to update L<http://dev.perl.org/perl5/>.
1102
1103
1104 =head1 SOURCE
1105
1106 Based on
1107 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
1108 plus a whole bunch of other sources, including private correspondence.
1109
1110 =cut
1111