This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
RMG - RCs are now listed in perlhist
[perl5.git] / Porting / release_managers_guide.pod
CommitLineData
49781f4a
AB
1=encoding utf8
2
7277a900
GS
3=head1 NAME
4
5release_managers_guide - Releasing a new version of perl 5.x
6
dc0a4df9
DM
7Note that things change at each release, so there may be new things not
8covered here, or tools may need updating.
9
c78277ad
DR
10=head1 MAKING A CHECKLIST
11
12If you are preparing to do a release, you can run the
13F<Porting/make-rmg-checklist> script to generate a new version of this
14document that starts with a checklist for your release.
15
16This script is run as:
17
18 perl Porting/make-rmg-checklist \
19 --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod
20
21You can also pass the C<--html> flag to generate an HTML document instead of
22POD.
f6af4394 23
0056d3d2
DR
24 perl Porting/make-rmg-checklist --html \
25 --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html
26
7277a900
GS
27=head1 SYNOPSIS
28
f6af4394 29This document describes the series of tasks required - some automatic, some
dc0a4df9
DM
30manual - to produce a perl release of some description, be that a release
31candidate, or final, numbered release of maint or blead.
f6af4394 32
8c35d285 33The release process has traditionally been executed by the current
ee76d676
JV
34pumpking. Blead releases from 5.11.0 forward are made each month on the
3520th by a non-pumpking release engineer. The release engineer roster
36and schedule can be found in Porting/release_schedule.pod.
7277a900 37
fdaa3f94
CBW
38This document both helps as a check-list for the release engineer
39and is a base for ideas on how the various tasks could be automated
8c35d285 40or distributed.
7277a900 41
da571fa1 42The checklist of a typical release cycle is as follows:
f6af4394 43
636a1918 44 (5.10.1 is released, and post-release actions have been done)
f6af4394
DM
45
46 ...time passes...
47
f6af4394
DM
48 a few weeks before the release, a number of steps are performed,
49 including bumping the version to 5.10.2
636a1918 50
e158965a 51 ...a few weeks pass...
46743ef7 52
f6af4394
DM
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
c5b87fed 58 perldelta.pod
f6af4394
DM
59
60 ... the cycle continues ...
7277a900
GS
61
62=head1 DETAILS
63
6a958a95
DM
64Some of the tasks described below apply to all four types of
65release of Perl. (blead, RC, final release of maint, final
8c35d285 66release of blead). Some of these tasks apply only to a subset
fdaa3f94 67of these release types. If a step does not apply to a given
8c35d285
JV
68type of release, you will see a notation to that effect at
69the beginning of the step.
70
71=head2 Release types
72
73=over 4
74
8c35d285
JV
75=item Release Candidate (RC)
76
d60a1044
DM
77A release candidate is an attempt to produce a tarball that is a close as
78possible to the final release. Indeed, unless critical faults are found
79during the RC testing, the final release will be identical to the RC
80barring a few minor fixups (updating the release date in F<perlhist.pod>,
81removing the RC status from F<patchlevel.h>, etc). If faults are found,
82then the fixes should be put into a new release candidate, never directly
83into a final release.
8c35d285 84
6a958a95
DM
85
86=item Stable/Maint release (MAINT).
87
88A release with an even version number, and subversion number > 0, such as
895.14.1 or 5.14.2.
8c35d285
JV
90
91At this point you should have a working release candidate with few or no
92changes since.
93
94It's essentially the same procedure as for making a release candidate, but
95with a whole bunch of extra post-release steps.
96
74648505
DM
97Note that for a maint release there are two versions of this guide to
98consider: the one in the maint branch, and the one in blead. Which one to
99use is a fine judgement. The blead one will be most up-to-date, while
100it might describe some steps or new tools that aren't applicable to older
101maint branches. It is probably best to review both versions of this
102document, but to most closely follow the steps in the maint version.
103
6a958a95
DM
104=item A blead point release (BLEAD-POINT)
105
106A release with an odd version number, such as 5.15.0 or 5.15.1.
107
108This isn't for production, so it has less stability requirements than for
109other release types, and isn't preceded by RC releases. Other than that,
110it is similar to a MAINT release.
111
112=item Blead final release (BLEAD-FINAL)
113
114A release with an even version number, and subversion number == 0, such as
dc0a4df9 1155.14.0. That is to say, it's the big new release once per year.
8c35d285
JV
116
117It's essentially the same procedure as for making a release candidate, but
6a958a95 118with a whole bunch of extra post-release steps, even more than for MAINT.
8c35d285
JV
119
120=back
7277a900 121
da571fa1 122=for checklist begin
dc0a4df9 123
fd838dcf
JV
124=head2 Prerequisites
125
126Before you can make an official release of perl, there are a few
127hoops you need to jump through:
128
00c28750 129=head3 PAUSE account with pumpkin status
8c35d285 130
fd838dcf
JV
131Make sure you have a PAUSE account suitable for uploading a perl release.
132If you don't have a PAUSE account, then request one:
133
134 https://pause.perl.org/pause/query?ACTION=request_id
135
9a3b7d40
FR
136Check that your account is allowed to upload perl distros: go to
137L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that
138your PAUSE ID is listed there. If not, ask Andreas KE<0xf6>nig to add your ID
139to the list of people allowed to upload something called perl. You can find
140Andreas' email address at:
4d2c8158 141
fd838dcf
JV
142 https://pause.perl.org/pause/query?ACTION=pause_04imprint
143
00c28750 144=head3 search.cpan.org pumpkin status
fdabea7a
JV
145
146Make sure that search.cpan.org knows that you're allowed to upload
147perl distros. Contact Graham Barr to make sure that you're on the right
148list.
149
a72d816c
RS
150=head3 rt.perl.org update access
151
152Make sure you have permission to close tickets on L<http://rt.perl.org/>
153so you can respond to bug report as necessary during your stint. If you
154don't, make an account (if you don't have one) and contact the pumpking
155with your username to get ticket-closing permission.
156
da571fa1 157=head3 git checkout and commit bit
fd838dcf
JV
158
159You will need a working C<git> installation, checkout of the perl
160git repository and perl commit bit. For information about working
c222ef46 161with perl and git, see F<pod/perlgit.pod>.
fd838dcf
JV
162
163If you are not yet a perl committer, you won't be able to make a
164release. Have a chat with whichever evil perl porter tried to talk
165you into the idea in the first place to figure out the best way to
166resolve the issue.
167
845a9291
MM
168=head3 git clone of https://github.com/perlorg/perlweb
169
170For updating the L<http://dev.perl.org> web pages, either a Github account or
171sweet-talking somebody with a Github account into obedience is needed. This
172is only needed on the day of the release or shortly afterwards.
173
da571fa1 174=head3 Quotation for release announcement epigraph
f6af4394 175
dffcb1c0 176You will need a quotation to use as an epigraph to your release announcement.
46743ef7 177
2e831dfd 178=head2 Building a release - advance actions
8c35d285 179
9c39c536
A
180The work of building a release candidate for an even numbered release
181(BLEAD-FINAL) of perl generally starts several weeks before the first
182release candidate. Some of the following steps should be done regularly,
183but all I<must> be done in the run up to a release.
7277a900 184
dc0a4df9 185=head3 dual-life CPAN module synchronisation
f6af4394 186
1d84c074 187To see which core distro versions differ from the current CPAN versions:
f6af4394 188
1d84c074 189 $ ./perl -Ilib Porting/core-cpan-diff -x -a
7277a900 190
1dbf7599
DG
191However, this only checks whether the version recorded in
192F<Porting/Maintainers.pl> differs from the latest on CPAN. It doesn't tell you
193if the code itself has diverged from CPAN.
7277a900 194
1d84c074
JL
195You can also run an actual diff of the contents of the modules, comparing core
196to CPAN, to ensure that there were no erroneous/extraneous changes that need to
197be dealt with. You do this by not passing the C<-x> option:
7277a900 198
1d84c074
JL
199 $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
200
3804a1f7
SH
201Passing C<-u cpan> will probably be helpful, since it limits the search to
202distributions with 'cpan' upstream source. (It's OK for blead upstream to
203differ from CPAN because those dual-life releases usually come I<after> perl
204is released.)
1dbf7599
DG
205
206See also the C<-d> and C<-v> options for more detail (and the C<-u> option as
207mentioned above). You'll probably want to use the C<-c cachedir> option to
208avoid repeated CPAN downloads and may want to use C<-m file:///mirror/path> if
209you made a local CPAN mirror. Note that a minicpan mirror won't actually work,
210but can provide a good first pass to quickly get a list of modules which
211definitely haven't changed, to avoid having to download absolutely everything.
212
193c036f
SH
213For a BLEAD-POINT or BLEAD-FINAL release with 'cpan' upstream, if a CPAN
214release appears to be ahead of blead, then consider updating it (or asking the
215relevant porter to do so). (However, if this is a BLEAD-FINAL release or one of
216the last BLEAD-POINT releases before it and hence blead is in some kind of
217"code freeze" state (e.g. the sequence might be "contentious changes freeze",
218then "user-visible changes freeze" and finally "full code freeze") then any
219CPAN module updates must be subject to the same restrictions, so it may not be
220possible to update all modules until after the BLEAD-FINAL release.) If blead
221contains edits to a 'cpan' upstream module, this is naughty but sometimes
222unavoidable to keep blead tests passing. Make sure the affected file has a
223CUSTOMIZED entry in F<Porting/Maintainers.pl>.
7277a900 224
6a958a95 225If you are making a MAINT release, run C<core-cpan-diff> on both blead and
636a1918
DM
226maint, then diff the two outputs. Compare this with what you expect, and if
227necessary, fix things up. For example, you might think that both blead
228and maint are synchronised with a particular CPAN module, but one might
fdaa3f94 229have some extra changes.
636a1918 230
9c39c536
A
231=head3 How to sync a CPAN module with a cpan/ distro
232
233=over 4
234
235=item *
236
237Fetch the most recent version from CPAN.
238
239=item *
240
241Unpack the retrieved tarball. Rename the old directory; rename the new
242directory to the original name.
243
244=item *
245
9e40a104 246Restore any F<.gitignore> file. This can be done by issuing
02cbdfef 247C<git checkout .gitignore> in the F<cpan/Distro> directory.
9c39c536
A
248
249=item *
250
251Remove files we do not need. That is, remove any files that match the
f5957b2f 252entries in C<@IGNORABLE> in F<Porting/Maintainer.pl>, and anything that
9c39c536
A
253matches the C<EXCLUDED> section of the distro's entry in the C<%Modules>
254hash.
255
256=item *
257
258Restore any files mentioned in the C<CUSTOMIZED> section, using
259C<git checkout>. Make any new customizations if necessary. Also,
260restore any files that are mentioned in C<@IGNORE>, but were checked
c5fb089a 261into the repository anyway.
9c39c536
A
262
263=item *
264
265For any new files in the distro, determine whether they are needed.
266If not, delete them, and list them in either C<EXCLUDED> or C<@INGORE>.
267Otherwise, add them to C<MANIFEST>, and run C<git add> to add the files
268to the repository.
269
270=item *
271
272For any files that are gone, remove them from C<MANIFEST>, and use
273C<git rm> to tell git the files will be gone.
274
275=item *
276
277If the C<MANIFEST> file was changed in any of the previous steps, run
278C<perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST>.
279
280=item *
281
282For any files that have an execute bit set, either remove the execute
02cbdfef 283bit, or edit F<Porting/exec-bit.txt>
9c39c536
A
284
285=item *
286
0b7399e1 287Run C<make> (or C<nmake> on Windows), see if C<perl> compiles.
9c39c536
A
288
289=item *
290
291Run the tests for the package.
292
293=item *
294
02cbdfef 295Run the tests in F<t/porting>.
9c39c536
A
296
297=item *
298
02cbdfef 299Update the C<DISTRIBUTION> entry in F<Porting/Maintainers.pl>.
9c39c536
A
300
301=item *
302
303Run a full configure/build/test cycle.
304
305=item *
306
307If everything is ok, commit the changes.
308
309=back
310
311For entries with a non-simple C<FILES> section, or with a C<MAP>, you
312may have to take more steps than listed above.
313
02cbdfef 314F<Porting/sync-with-cpan> is a script that automates most of the steps
0b7399e1
SH
315above; but see the comments at the beginning of the file. In particular,
316it has not yet been exercised on Windows, but will certainly require a set
317of Unix tools such as Cygwin, and steps that run C<make> will need to run
318C<nmake> instead.
9c39c536 319
dc0a4df9 320=head3 dual-life CPAN module stability
7277a900 321
f6af4394 322Ensure dual-life CPAN modules are stable, which comes down to:
7277a900 323
ed380305
KW
324 for each module that fails its regression tests on $current
325 did it fail identically on $previous?
326 if yes, "SEP" (Somebody Else's Problem)
327 else work out why it failed (a bisect is useful for this)
328
329 attempt to group failure causes
330
331 for each failure cause
332 is that a regression?
333 if yes, figure out how to fix it
334 (more code? revert the code that broke it)
335 else
336 (presumably) it's relying on something un-or-under-documented
337 should the existing behaviour stay?
338 yes - goto "regression"
339 no - note it in perldelta as a significant bugfix
340 (also, try to inform the module's author)
1aff5354 341
00c28750 342=head3 monitor smoke tests for failures
7277a900 343
5157df7a 344Similarly, monitor the smoking of core tests, and try to fix. See
c840542b
MB
345L<http://doc.procura.nl/smoke/index.html> and L<http://perl5.test-smoke.org/>
346for a summary. See also
5157df7a
AB
347L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has
348the raw reports.
7277a900 349
636a1918
DM
350Similarly, monitor the smoking of perl for compiler warnings, and try to
351fix.
352
00c28750 353=head3 update perldelta
636a1918 354
f6af4394 355Get perldelta in a mostly finished state.
db3f805e 356
04c2c53e 357Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
636a1918
DM
358every section it lists is, if necessary, populated and complete. Copy
359edit the whole document.
f6af4394 360
1dbf7599
DG
361You won't be able to automatically fill in the "Updated Modules" section until
362after Module::CoreList is updated (as described below in
363L<"update Module::CoreList">).
f6af4394 364
dc0a4df9
DM
365=head3 Bump the version number
366
30f926b5
JL
367Do not do this yet for a BLEAD-POINT release! You will do this at the end of
368the release process.
369
dc0a4df9 370Increase the version number (e.g. from 5.12.0 to 5.12.1).
04dbb930 371
30f926b5 372For a release candidate for a stable perl, this should happen a week or two
04dbb930
DG
373before the first release candidate to allow sufficient time for testing and
374smoking with the target version built into the perl executable. For
c5fb089a 375subsequent release candidates and the final release, it is not necessary to
04dbb930 376bump the version further.
f6af4394 377
8b2227e6 378There is a tool to semi-automate this process:
f6af4394 379
8b2227e6 380 $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1
f6af4394 381
8b2227e6
LB
382Remember that this tool is largely just grepping for '5.10.0' or whatever,
383so it will generate false positives. Be careful not change text like
384"this was fixed in 5.10.0"!
ceb7f800 385
8b2227e6 386Use git status and git diff to select changes you want to keep.
ceb7f800 387
f6af4394
DM
388Be particularly careful with F<INSTALL>, which contains a mixture of
389C<5.10.0>-type strings, some of which need bumping on every release, and
e03f126c
Z
390some of which need to be left unchanged.
391The line in F<INSTALL> about "is binary incompatible with" requires a
392correct choice of earlier version to declare incompatibility with.
393
cdf175f7
SH
394For the first RC release leading up to a BLEAD-FINAL release, update the
395description of which releases are now "officially" supported in
396F<pod/perlpolicy.pod>.
397
6a958a95
DM
398When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
399C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
ac2aec01
SH
400you're releasing, unless you're absolutely sure the release you're about to
401make is 100% binary compatible to an earlier release. When releasing a MAINT
402perl version, the C<PERL_API_*> constants C<MUST NOT> be changed as we aim
403to guarantee binary compatibility in maint branches.
45ce9531 404
17163f85
DM
405After editing, regenerate uconfig.h (this must be run on a system with a
406/bin/sh available):
22be9667 407
ed380305 408 $ perl regen/uconfig_h.pl
22be9667 409
78957677
JL
410This might not cause any new changes.
411
22be9667
JV
412Test your changes:
413
ed380305
KW
414 $ git clean -xdf # careful if you don't have local files to keep!
415 $ ./Configure -des -Dusedevel
416 $ make
417 $ make test
22be9667 418
54356a6f
JV
419Commit your changes:
420
ed380305
KW
421 $ git status
422 $ git diff
423 B<review the delta carefully>
54356a6f 424
ed380305 425 $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
dc0a62a1 426
21768cb3 427At this point you may want to compare the commit with a previous bump to
ac2aec01 428see if they look similar. See commit f7cf42bb69 for an example of a
21768cb3
FC
429previous version bump.
430
dc0a4df9
DM
431When the version number is bumped, you should also update Module::CoreList
432(as described below in L<"update Module::CoreList">) to reflect the new
81fc59ef
DG
433version number.
434
dc0a4df9 435=head3 update INSTALL
dc0a62a1
DM
436
437Review and update INSTALL to account for the change in version number;
438in particular, the "Coexistence with earlier versions of perl 5" section.
439
6a958a95
DM
440Be particularly careful with the section "Upgrading from 5.X.Y or earlier".
441The "X.Y" needs to be changed to the most recent version that we are
442I<not> binary compatible with.
443
444For MAINT and BLEAD-FINAL releases, this needs to refer to the last
445release in the previous development cycle (so for example, for a 5.14.x
446release, this would be 5.13.11).
447
448For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
449release (so for 5.15.3 this would be 5.15.2).
450
52d097d9
S
451=head3 Check copyright years
452
453Check that the copyright years are up to date by running:
454
455 $ ./perl t/porting/copyright.t --now
456
457Remedy any test failures by editing README or perl.c accordingly (search for
458the "Copyright"). If updating perl.c, check if the file's own copyright date in
459the C comment at the top needs updating, as well as the one printed by C<-v>.
460
dc0a4df9 461=head3 Check more build configurations
b82efa27 462
d8fc5aa0
DR
463Try running the full test suite against multiple Perl configurations. Here are
464some sets of Configure flags you can try:
52a66c2c 465
d8fc5aa0 466=over 4
7277a900 467
d8fc5aa0
DR
468=item *
469
470C<-Duseshrplib -Dusesitecustomize>
471
472=item *
473
474C<-Duserelocatableinc>
475
476=item *
477
478C<-Dusethreads>
479
480=back
7277a900 481
d8fc5aa0
DR
482If you have multiple compilers on your machine, you might also consider
483compiling with C<-Dcc=$other_compiler>.
dc0a4df9
DM
484
485=head3 update perlport
7277a900 486
347f5124
RGS
487L<perlport> has a section currently named I<Supported Platforms> that
488indicates which platforms are known to build in the current release.
489If necessary update the list and the indicated version number.
490
1dbf7599
DG
491=head3 check a readonly build
492
493Even before other prep work, follow the steps in L<build the tarball> and test
494it locally. Because a perl source tarballs sets many files read-only, it could
495test differently than tests run from the repository. After you're sure
496permissions aren't a problem, delete the generated directory and tarballs.
6a958a95 497
2e831dfd
DM
498=head2 Building a release - on the day
499
b1288acc 500This section describes the actions required to make a release
f6b1864d 501that are performed near to, or on the actual release day.
2e831dfd 502
dc0a4df9 503=head3 re-check earlier actions
2e831dfd 504
dc0a4df9 505Review all the actions in the previous section,
2e831dfd
DM
506L<"Building a release - advance actions"> to ensure they are all done and
507up-to-date.
508
ff721450
JL
509=head3 create a release branch
510
511For BLEAD-POINT releases, making a release from a release branch avoids the
512need to freeze blead during the release. This is less important for
513BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in
514those cases. Create the branch by running
515
516 git checkout -b release-5.xx.yy
517
dc0a4df9 518=head3 build a clean perl
8c35d285 519
1dbf7599 520Make sure you have a gitwise-clean perl directory (no modified files,
a0db33fe 521unpushed commits etc):
8c35d285 522
a0db33fe 523 $ git status
24c5e187 524 $ git clean -dxf
8c35d285 525
dc0a4df9 526then configure and build perl so that you have a Makefile and porting tools:
8c35d285 527
52a66c2c 528 $ ./Configure -Dusedevel -des && make
8c35d285 529
dc0a4df9 530=head3 update Module::CoreList
8c35d285 531
0429cb0e
SH
532=head4 Bump Module::CoreList* $VERSIONs
533
534If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for
535every RC; in RC1, bump the version to a new clean number that will
536appear in the final release, and leave as-is for the later RCs and final).
537It may also happen that C<Module::CoreList> has been modified in blead, and
538hence has a new version number already. (But make sure it is not the same
539number as a CPAN release.)
540
541C<$Module::CoreList::TieHashDelta::VERSION> and
542C<$Module::CoreList::Utils::VERSION> should always be equal to
543C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match
544before proceeding.
545
546=head4 Update C<Module::CoreList> with module version data for the new release.
bfadf2ba 547
6a958a95 548Note that if this is a MAINT release, you should run the following actions
1bac61bb 549from the maint branch, but commit the C<CoreList.pm> changes in
a9d1f3db
LB
550I<blead> and subsequently cherry-pick any releases since the last
551maint release and then your recent commit. XXX need a better example
bfadf2ba 552
89781932
DM
553[ Note that the procedure for handling Module::CoreList in maint branches
554is a bit complex, and the RMG currently don't describe a full and
555workable approach. The main issue is keeping Module::CoreList
556and its version number synchronised across all maint branches, blead and
557CPAN, while having to bump its version number for every RC release.
558See this brief p5p thread:
559
560 Message-ID: <20130311174402.GZ2294@iabyn.com>
561
562If you can devise a workable system, feel free to try it out, and to
38e4b857 563update the RMG accordingly!
89781932
DM
564
565DAPM May 2013 ]
566
a0db33fe 567F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
218a07e7
SH
568modules on CPAN. It can use a full, local CPAN mirror and/or fall back
569on HTTP::Tiny to fetch package metadata remotely.
bfadf2ba 570
fdaa3f94 571(If you'd prefer to have a full CPAN mirror, see
bfadf2ba
JV
572http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
573
a0db33fe 574Then change to your perl checkout, and if necessary,
bfadf2ba 575
595f83ae 576 $ make
bfadf2ba 577
bf8ea215 578Then, If you have a local CPAN mirror, run:
bfadf2ba 579
bfadf2ba
JV
580 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
581
582Otherwise, run:
583
bfadf2ba
JV
584 $ ./perl -Ilib Porting/corelist.pl cpan
585
52a66c2c 586This will chug for a while, possibly reporting various warnings about
2a720090 587badly-indexed CPAN modules unrelated to the modules actually in core.
2ce7d676 588Assuming all goes well, it will update
ab0bff1f 589F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly
244e6e4e
SH
590F<dist/Module-CoreList/lib/Module/CoreList.pod> and/or
591F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
bfadf2ba 592
ab0bff1f 593Check those files over carefully:
bfadf2ba 594
d5bddf6e 595 $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
ab0bff1f 596 $ git diff dist/Module-CoreList/lib/Module/CoreList.pod
244e6e4e 597 $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm
1dbf7599 598
00c28750
DR
599=head4 Bump version in Module::CoreList F<Changes>
600
0429cb0e 601Also edit Module::CoreList's new version number in its F<Changes> file.
e8c01f92 602
00c28750
DR
603=head4 Add Module::CoreList version bump to perldelta
604
70855f8b
FC
605Add a perldelta entry for the new Module::CoreList version.
606
da571fa1
DR
607=for checklist skip RC
608
48100be1 609=head4 Update C<%Module::CoreList::released> and C<CAVEATS>
da571fa1 610
f1c895b1 611For any release except an RC:
bfadf2ba 612
fdaa3f94 613=over 4
bfadf2ba
JV
614
615=item *
616
617Update this version's entry in the C<%released> hash with today's date.
618
619=item *
620
621Make sure that the script has correctly updated the C<CAVEATS> section
688b7920
A
622(Note, the C<CAVEATS> section is in
623F<dist/Module-CoreList/lib/Module/CoreList.pod>)
bfadf2ba
JV
624
625=back
626
00c28750
DR
627=head4 Commit Module::CoreList changes
628
bfadf2ba 629Finally, commit the new version of Module::CoreList:
6a958a95 630(unless this is for MAINT; in which case commit it to blead first, then
a0db33fe 631cherry-pick it back).
bfadf2ba 632
0429cb0e 633 $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/Changes dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod dist/Module-CoreList/lib/Module/CoreList/Utils.pm
bfadf2ba 634
1dbf7599
DG
635=head4 Rebuild and test
636
637Build and test to get the changes into the currently built lib directory and to ensure
638all tests are passing.
639
640=head3 finalize perldelta
641
642Finalize the perldelta. In particular, fill in the Acknowledgements
643section, which can be generated with something like:
644
645 $ perl Porting/acknowledgements.pl v5.15.0..HEAD
646
2c5d738b
SH
647Fill in the "New/Updated Modules" sections now that Module::CoreList is updated:
648
649 $ ./perl -Ilib Porting/corelist-perldelta.pl --mode=update pod/perldelta.pod
650
651Ideally, also fill in a summary of the major changes to each module for which
652an entry has been added by F<corelist-perldelta.pl>.
1dbf7599
DG
653
654Re-read the perldelta to try to find any embarrassing typos and thinkos;
655remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
656with any serious issues for which fixes are not going to happen now; and
657run through pod and spell checkers, e.g.
658
659 $ podchecker -warnings -warnings pod/perldelta.pod
660 $ spell pod/perldelta.pod
661
662Also, you may want to generate and view an HTML version of it to check
663formatting, e.g.
664
665 $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html
666
667Another good HTML preview option is http://search.cpan.org/pod2html
668
669If you make changes, be sure to commit them.
670
671=for checklist skip BLEAD-POINT MAINT RC
672
673=head3 remove stale perldeltas
674
675For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
1f6591ac 676from the BLEAD-POINT releases since the previous BLEAD-FINAL should have
1dbf7599
DG
677now been consolidated into the current perldelta, and hence are now just
678useless clutter. They can be removed using:
679
680 $ git rm <file1> <file2> ...
681
682For example, for RC0 of 5.16.0:
683
684 $ cd pod
685 $ git rm perldelta515*.pod
686
1f6591ac 687=for checklist skip BLEAD-FINAL BLEAD-POINT
1dbf7599
DG
688
689=head3 add recent perldeltas
690
691For the first RC for a MAINT release, copy in any recent perldeltas from
692blead that have been added since the last release on this branch. This
693should include any recent maint releases on branches older than your one,
694but not newer. For example if you're producing a 5.14.x release, copy any
695perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from
6965.16.x or higher. Remember to
697
698 $ git add <file1> <file2> ...
699
700=head3 update and commit perldelta files
701
702If you have added or removed any perldelta files via the previous two
703steps, then edit F<pod/perl.pod> to add/remove them from its table of
704contents, then run F<Porting/pod_rules.pl> to propagate your changes there
705into all the other files that mention them (including F<MANIFEST>). You'll
706need to C<git add> the files that it changes.
707
708Then build a clean perl and do a full test
709
710 $ git status
711 $ git clean -dxf
712 $ ./Configure -Dusedevel -des
713 $ make
714 $ make test
715
716Once all tests pass, commit your changes.
717
718=head3 build a clean perl
719
720If you skipped the previous step (adding/removing perldeltas),
721again, make sure you have a gitwise-clean perl directory (no modified files,
722unpushed commits etc):
723
724 $ git status
725 $ git clean -dxf
726
727then configure and build perl so that you have a Makefile and porting tools:
728
729 $ ./Configure -Dusedevel -des && make
730
1f6591ac 731=for checklist skip BLEAD-FINAL BLEAD-POINT
80dd5f25
DM
732
733=head3 synchronise from blead's perlhist.pod
734
735For the first RC for a MAINT release, copy in the latest
736F<pod/perlhist.pod> from blead; this will include details of newer
737releases in all branches. In theory, blead's version should be a strict
738superset of the one in this branch, but it's probably safest to diff them
739first to ensure that there's nothing in this branch that was forgotten
740from blead:
741
742 $ diff pod/perlhist.pod ..../blead/pod/perlhist.pod
743 $ cp ..../blead/pod/perlhist.pod pod/
744 $ git commit -m 'sync perlhist from blead' pod/perlhist.pod
745
dc0a4df9 746=head3 update perlhist.pod
a0db33fe 747
e8a7a70e
JV
748Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
749
750 David 5.10.1 2009-Aug-06
a0db33fe 751
a420fd35
MH
752List yourself in the left-hand column, and if this is the first release
753that you've ever done, make sure that your name is listed in the section
754entitled C<THE KEEPERS OF THE PUMPKIN>.
a0db33fe 755
56e2d9fb 756I<If you're making a BLEAD-FINAL release>, also update the "SELECTED
bd4ce907
RS
757RELEASE SIZES" section with the output of
758F<Porting/perlhist_calculate.pl>.
759
a0db33fe
DM
760Be sure to commit your changes:
761
762 $ git commit -m 'add new release to perlhist' pod/perlhist.pod
8c35d285 763
da571fa1 764=for checklist skip BLEAD-POINT
dc0a4df9
DM
765
766=head3 update patchlevel.h
8c35d285 767
6a958a95 768I<You MUST SKIP this step for a BLEAD-POINT release>
d7eb1120 769
a42352ee
DM
770Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
771a final release, remove it. For example:
d7eb1120
DM
772
773 static const char * const local_patches[] = {
774 NULL
775 + ,"RC1"
776 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
777
778Be sure to commit your change:
779
780 $ git commit -m 'bump version to RCnnn' patchlevel.h
781
4612967b
CBW
782=head3 run makemeta to update META files
783
e4fbed99 784 $ ./perl -Ilib Porting/makemeta
4612967b
CBW
785
786Be sure to commit any changes (if applicable):
787
e4fbed99 788 $ git status # any changes?
4612967b 789 $ git commit -m 'Update META files' META.*
dc0a4df9
DM
790
791=head3 build, test and check a fresh perl
d7eb1120 792
a0db33fe
DM
793Build perl, then make sure it passes its own test suite, and installs:
794
795 $ git clean -xdf
a42352ee
DM
796 $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
797
798 # or if it's an odd-numbered version:
a0db33fe 799 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
a42352ee 800
a0db33fe
DM
801 $ make test install
802
52a66c2c
DM
803Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
804C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
a0db33fe 805especially as regards version numbers, patch and/or RC levels, and @INC
c5fb089a 806paths. Note that as they have been built from a git working
52a66c2c 807directory, they will still identify themselves using git tags and
01725c10
A
808commits. (Note that for an odd-numbered version, perl will install
809itself as C<perl5.x.y>). C<perl -v> will identify itself as:
810
78957677 811 This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))
01725c10 812
78957677 813where 5.X.Z is the latest tag, NNN the number of commits since this tag,
01725c10 814and C<< deadbeef >> commit of that tag.
52a66c2c
DM
815
816Then delete the temporary installation.
817
c90225ed 818=head3 create the release tag
dc0a4df9 819
c90225ed 820Create the tag identifying this release (e.g.):
96054f12 821
b6d23947 822 $ git tag v5.11.0 -m "First release of the v5.11 series!"
e8c01f92 823
6a958a95 824It is B<VERY> important that from this point forward, you not push
f662f3b7
JV
825your git changes to the Perl master repository. If anything goes
826wrong before you publish your newly-created tag, you can delete
827and recreate it. Once you push your tag, we're stuck with it
828and you'll need to use a new version number for your release.
829
dc0a4df9 830=head3 build the tarball
a0db33fe 831
0dcf3caa 832Before you run the following, you might want to install 7-Zip (the
0dcb816b 833C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or
0dcf3caa
LB
834the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian,
835or the C<advancecomp> port on macports - 7-Zip on Windows is the
836same code as AdvanceCOMP, so Windows users get the smallest files
837first time). These compress about 5% smaller than gzip and bzip2.
838Over the lifetime of your distribution this will save a lot of
839people a small amount of download time and disk space, which adds
840up.
841
8c35d285
JV
842Create a tarball. Use the C<-s> option to specify a suitable suffix for
843the tarball and directory name:
844
ed380305 845 $ cd root/of/perl/tree
3635a175 846 $ make distclean # make sure distclean works
ed380305 847 $ git clean -xdf # make sure perl and git agree on files
c23867c2 848 # git clean should not output anything!
ed380305 849 $ git status # and there's nothing lying around
8c35d285 850
ed380305
KW
851 $ perl Porting/makerel -b -s RC1 # for a release candidate
852 $ perl Porting/makerel -b # for a final release
8c35d285
JV
853
854This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
ac2aec01
SH
855the MANIFEST files into it, sets the correct permissions on them, then
856tars it up as F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a
857C<tar.bz2> file.
8c35d285 858
6480287f
MT
859If you're getting your tarball suffixed with -uncommitted and you're sure
860your changes were all committed, you can override the suffix with:
861
862 $ perl Porting/makerel -b -s ''
96054f12 863
8c35d285
JV
864XXX if we go for extra tags and branches stuff, then add the extra details
865here
866
dc0a4df9 867Finally, clean up the temporary directory, e.g.
a42352ee
DM
868
869 $ rm -rf ../perl-x.y.z-RC1
870
dc0a4df9
DM
871=head3 test the tarball
872
00c28750 873Once you have a tarball it's time to test the tarball (not the repository).
dc0a4df9 874
00c28750 875=head4 Copy the tarball to a web server
a42352ee 876
8c35d285
JV
877Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
878have access to.
879
00c28750 880=head4 Download the tarball to another machine
8c35d285 881
fdaa3f94 882Download the tarball to some other machine. For a release candidate,
8c35d285
JV
883you really want to test your tarball on two or more different platforms
884and architectures. The #p5p IRC channel on irc.perl.org is a good place
885to find willing victims.
886
00c28750 887=head4 Check that F<Configure> works
8c35d285
JV
888
889Check that basic configuration and tests work on each test machine:
890
e07c44df
MH
891 $ ./Configure -des && make all test
892
893 # Or for a development release:
bf8aad21 894 $ ./Configure -Dusedevel -des && make all test
f6af4394 895
00c28750 896=head4 Run the test harness and install
f6af4394 897
8c35d285
JV
898Check that the test harness and install work on each test machine:
899
a42352ee 900 $ make distclean
8c35d285 901 $ ./Configure -des -Dprefix=/install/path && make all test_harness install
a42352ee 902 $ cd /install/path
8c35d285 903
00c28750 904=head4 Check C<perl -v> and C<perl -V>
8c35d285
JV
905
906Check that the output of C<perl -v> and C<perl -V> are as expected,
907especially as regards version numbers, patch and/or RC levels, and @INC
fdaa3f94 908paths.
8c35d285
JV
909
910Note that the results may be different without a F<.git/> directory,
911which is why you should test from the tarball.
912
00c28750 913=head4 Run the Installation Verification Procedure utility
459fc3ca 914
9651cacc 915 $ ./perl utils/perlivp
459fc3ca
DM
916 ...
917 All tests successful.
918 $
919
00c28750 920=head4 Compare the installed paths to the last release
459fc3ca 921
d60a1044
DM
922Compare the pathnames of all installed files with those of the previous
923release (i.e. against the last installed tarball on this branch which you
924have previously verified using this same procedure). In particular, look
925for files in the wrong place, or files no longer included which should be.
926For example, suppose the about-to-be-released version is 5.10.1 and the
927previous is 5.10.0:
928
929 cd installdir-5.10.0/
930 find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
931 cd installdir-5.10.1/
932 find . -type f | sort > /tmp/f2
933 diff -u /tmp/f[12]
934
29205e9c 935=head4 Bootstrap the CPAN client
d60a1044 936
8c35d285
JV
937Bootstrap the CPAN client on the clean install:
938
29205e9c 939 $ bin/cpan
8c35d285 940
61a1ab54
MH
941 # Or, perhaps:
942 $ bin/cpan5.xx.x
943
29205e9c 944=head4 Install the Inline module with CPAN and test it
8c35d285 945
a42352ee
DM
946Try installing a popular CPAN module that's reasonably complex and that
947has dependencies; for example:
8c35d285 948
65651c62 949 CPAN> install Inline::C
a42352ee 950 CPAN> quit
8c35d285
JV
951
952Check that your perl can run this:
953
16c60e4e 954 $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
a42352ee
DM
955 42
956 $
8c35d285 957
00c28750 958=head4 Make sure that perlbug works
8c35d285 959
00c28750 960Test L<perlbug> with the following:
47b1f096 961
a14438df 962 $ bin/perlbug
47b1f096
DM
963 ...
964 Subject: test bug report
fdaa3f94
CBW
965 Local perl administrator [yourself]:
966 Editor [vi]:
967 Module:
968 Category [core]:
969 Severity [low]:
47b1f096
DM
970 (edit report)
971 Action (Send/Display/Edit/Subject/Save to File): f
fdaa3f94 972 Name of file to save message in [perlbug.rep]:
47b1f096
DM
973 Action (Send/Display/Edit/Subject/Save to File): q
974
975and carefully examine the output (in F<perlbug.rep]>), especially
976the "Locally applied patches" section. If everything appears okay, then
75a012fe
DM
977delete the file, and try it again, this time actually submitting the bug
978report. Check that it shows up, then remember to close it!
47b1f096 979
da571fa1 980=for checklist skip BLEAD-POINT
dc0a4df9
DM
981
982=head3 monitor smokes
47b1f096 983
1dbf7599
DG
984XXX This is probably irrelevant if working on a release branch, though
985MAINT or RC might want to push a smoke branch and wait.
986
f6af4394
DM
987Wait for the smoke tests to catch up with the commit which this release is
988based on (or at least the last commit of any consequence).
7277a900 989
f6af4394
DM
990Then check that the smoke tests pass (particularly on Win32). If not, go
991back and fix things.
7277a900 992
6a958a95 993Note that for I<BLEAD-POINT> releases this may not be practical. It takes a
1eefd7d5 994long time for the smokers to catch up, especially the Win32
6a958a95
DM
995smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL>
996releases, but for I<BLEAD-POINT> releases sometimes the best you can do is
997to plead with people on IRC to test stuff on their platforms, fire away,
998and then hope for the best.
7277a900 999
dc0a4df9 1000=head3 upload to PAUSE
7277a900 1001
f6af4394 1002Once smoking is okay, upload it to PAUSE. This is the point of no return.
db3f805e
JV
1003If anything goes wrong after this point, you will need to re-prepare
1004a new release with a new minor version or RC number.
1005
a14438df
DM
1006 https://pause.perl.org/
1007
1008(Login, then select 'Upload a file to CPAN')
1009
45924287
RS
1010If your workstation is not connected to a high-bandwidth,
1011high-reliability connection to the Internet, you should probably use the
1012"GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
1013new release from wherever you put it for testers to find it. This will
1014eliminate anxious gnashing of teeth while you wait to see if your
101515 megabyte HTTP upload successfully completes across your slow, twitchy
c27b4e97
SH
1016cable modem. You can make use of your home directory on dromedary for
1017this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
1018F</home/USERNAME/public_html>, where F<USERNAME> is your login account
1019on dromedary. I<Remember>: if your upload is partially successful, you
1020may need to contact a PAUSE administrator or even bump the version of perl.
45924287 1021
a42352ee 1022Upload both the .gz and .bz2 versions of the tarball.
f6af4394 1023
1dbf7599
DG
1024Do not proceed any further until you are sure that your tarballs are on CPAN.
1025Check your authors directory www.cpan.org (the globally balanced "fast"
1026mirror) to confirm that your uploads have been successful.
c27b4e97 1027
1dbf7599 1028=for checklist skip RC BLEAD-POINT
00c28750
DR
1029
1030=head3 wait for indexing
1031
1dbf7599 1032I<You MUST SKIP this step for RC and BLEAD-POINT>
76526317
FR
1033
1034Wait until you receive notification emails from the PAUSE indexer
1035confirming that your uploads have been received. IMPORTANT -- you will
1036probably get an email that indexing has failed, due to module permissions.
1037This is considered normal.
1038
da571fa1 1039=for checklist skip BLEAD-POINT
dc0a4df9
DM
1040
1041=head3 disarm patchlevel.h
f6af4394 1042
6a958a95 1043I<You MUST SKIP this step for BLEAD-POINT release>
113f3f4c 1044
a42352ee 1045Disarm the F<patchlevel.h> change; for example,
d7eb1120
DM
1046
1047 static const char * const local_patches[] = {
1048 NULL
1049 - ,"RC1"
1050 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
1051
1052Be sure to commit your change:
1053
1054 $ git commit -m 'disarm RCnnn bump' patchlevel.h
dc0a4df9
DM
1055
1056=head3 announce to p5p
2e831dfd 1057
db3f805e 1058Mail p5p to announce your new release, with a quote you prepared earlier.
f6af4394 1059
098d30ef 1060Use the template at Porting/release_announcement_template.txt
dc0a4df9 1061
a8cecd9d
RS
1062Send a carbon copy to C<noc@metacpan.org>
1063
ff721450
JL
1064=head3 merge release branch back to blead
1065
c90225ed 1066Merge the (local) release branch back into master now, and delete it.
ff721450
JL
1067
1068 git checkout blead
1069 git pull
1070 git merge release-5.xx.yy
1071 git push
ff721450
JL
1072 git branch -d release-5.xx.yy
1073
121e9ff0
SH
1074Note: The merge will create a merge commit if other changes have been pushed
1075to blead while you've been working on your release branch. Do NOT rebase your
1076branch to avoid the merge commit (as you might normally do when merging a
1077small branch into blead) since doing so will invalidate the tag that you
1078created earlier.
1079
c90225ed
SH
1080=head3 publish the release tag
1081
1082Now that you've shipped the new perl release to PAUSE and pushed your changes
1083to the Perl master repository, it's time to publish the tag you created
1084earlier too (e.g.):
1085
1086 $ git push origin tag v5.11.0
1087
dc0a4df9 1088=head3 update epigraphs.pod
f6af4394 1089
85531b0a 1090Add your quote to F<Porting/epigraphs.pod> and commit it.
70d95cc9
SH
1091You can include the customary link to the release announcement even before your
1092message reaches the web-visible archives by looking for the X-List-Archive
1093header in your message after receiving it back via perl5-porters.
dc0a4df9 1094
b02b3ec7
DR
1095=head3 blog about your epigraph
1096
1097If you have a blog, please consider writing an entry in your blog explaining
1098why you chose that particular quote for your epigraph.
1099
da571fa1
DR
1100=for checklist skip RC
1101
dc0a4df9 1102=head3 Module::CoreList nagging
85531b0a 1103
bc4c40f2 1104I<You MUST SKIP this step for RC>
8c35d285 1105
75a012fe
DM
1106Remind the current maintainer of C<Module::CoreList> to push a new release
1107to CPAN.
7277a900 1108
da571fa1 1109=for checklist skip RC
dc0a4df9
DM
1110
1111=head3 new perldelta
a2cba4bc 1112
bc4c40f2 1113I<You MUST SKIP this step for RC>
7277a900 1114
bcfe7366 1115Create a new perldelta.
5ef3945b 1116
bcfe7366 1117=over 4
8e967a1c 1118
bcfe7366 1119=item *
8e967a1c 1120
bcfe7366 1121Confirm that you have a clean checkout with no local changes.
c5b87fed 1122
bcfe7366 1123=item *
17163f85 1124
bcfe7366 1125Run F<Porting/new-perldelta.pl>
8e967a1c 1126
bcfe7366 1127=item *
17163f85 1128
bcfe7366 1129Run the C<git add> commands it outputs to add new and modified files.
7277a900 1130
bcfe7366 1131=item *
7277a900 1132
bcfe7366 1133Verify that the build still works, by running C<./Configure> and
e0373c35 1134C<make test_porting>. (On Win32 use the appropriate make utility).
17163f85 1135
bcfe7366 1136=item *
17163f85 1137
bcfe7366
NC
1138If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>,
1139run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail.
1140Skip to the end of its test output to see the options it offers you.
57433fbf 1141
bcfe7366 1142=item *
75a012fe 1143
bcfe7366 1144When C<make test_porting> passes, commit the new perldelta.
75a012fe 1145
bcfe7366 1146=back
75a012fe 1147
21768cb3 1148At this point you may want to compare the commit with a previous bump to
ac2aec01 1149see if they look similar. See commit ba03bc34a4 for an example of a
75a012fe 1150previous version bump.
57433fbf 1151
30f926b5 1152=for checklist skip MAINT RC
dc0a4df9
DM
1153
1154=head3 bump version
57433fbf 1155
30f926b5 1156I<You MUST SKIP this step for RC and MAINT>
dc0a62a1 1157
6a958a95
DM
1158If this was a BLEAD-FINAL release (i.e. the first release of a new maint
1159series, 5.x.0 where x is even), then bump the version in the blead branch
1160in git, e.g. 5.12.0 to 5.13.0.
17163f85 1161
6d5e92cd
FC
1162First, add a new feature bundle to F<regen/feature.pl>, initially by just
1163copying the exiting entry, and bump the file's $VERSION (after the __END__
1164marker); e.g.
17163f85
DM
1165
1166 "5.14" => [qw(switch say state unicode_strings)],
1167 + "5.15" => [qw(switch say state unicode_strings)],
addebd58 1168
57fef7cc
FC
1169Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>.
1170
dc0a4df9
DM
1171Then follow the section L<"Bump the version number"> to bump the version
1172in the remaining files and test and commit.
17163f85 1173
30f926b5
JL
1174If this was a BLEAD-POINT release, then just follow the section
1175L<"Bump the version number">.
1176
2136887a
DG
1177After bumping the version, follow the section L<"update INSTALL"> to
1178ensure all version number references are correct.
17163f85 1179
5f9f8ddf
SH
1180(Note: The version is NOT bumped immediately after a MAINT release in order
1181to avoid confusion and wasted time arising from bug reports relating to
1182"intermediate versions" such as 5.20.1-and-a-bit: If the report is caused
1183by a bug that gets fixed in 5.20.2 and this intermediate version already
1184calls itself 5.20.2 then much time can be wasted in figuring out why there
1185is a failure from something that "should have been fixed". If the bump is
1186late then there is a much smaller window of time for such confusing bug
1187reports to arise. (The opposite problem -- trying to figure out why there
1188*is* a bug in something calling itself 5.20.1 when in fact the bug was
1189introduced later -- shouldn't arise for MAINT releases since they should,
1190in theory, only contain bug fixes but never regressions.))
1191
d5c37431
NC
1192=head3 clean build and test
1193
1194Run a clean build and test to make sure nothing obvious is broken.
1195
1196In particular, F<Porting/perldelta_template.pod> is intentionally exempted
1197from podchecker tests, to avoid false positives about placeholder text.
1198However, once it's copied to F<pod/perldelta.pod> the contents can now
ef4474b5
KW
1199cause test failures. Problems should resolved by doing one of the
1200following:
1201
1202=over
1203
1204=item 1
1205
1206Replace placeholder text with correct text.
1207
1208=item 2
1209
1210If the problem is from a broken placeholder link, you can add it to the
1211array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines
1212containing such links should be marked with C<XXX> so that they get
1213cleaned up before the next release.
1214
1215=item 3
1216
1217Following the instructions output by F<t/porting/podcheck.t> on how to
1218update its exceptions database.
1219
1220=back
d5c37431 1221
dc0a4df9
DM
1222=head3 push commits
1223
1224Finally, push any commits done above.
1225
1226 $ git push origin ....
1227
da571fa1 1228=for checklist skip BLEAD-POINT MAINT RC
dc0a4df9
DM
1229
1230=head3 create maint branch
17163f85 1231
6a958a95 1232I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
17163f85 1233
6a958a95
DM
1234If this was a BLEAD-FINAL release (i.e. the first release of a new maint
1235series, 5.x.0 where x is even), then create a new maint branch based on
1236the commit tagged as the current release.
7277a900 1237
233ca920
JV
1238Assuming you're using git 1.7.x or newer:
1239
17163f85 1240 $ git checkout -b maint-5.12 v5.12.0
233ca920 1241 $ git push origin -u maint-5.12
addebd58 1242
dc0a4df9 1243
da571fa1
DR
1244=for checklist skip BLEAD-POINT MAINT RC
1245
d5722260
DK
1246=head3 make the maint branch available in the APC
1247
1248Clone the new branch into /srv/gitcommon/branches on camel so the APC will
1249receive its changes.
1250
07697565 1251 $ git clone --branch maint-5.14 /gitroot/perl.git \
d5722260 1252 ? /srv/gitcommon/branches/perl-5.14.x
07697565 1253 $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x
d5722260
DK
1254
1255And nag the sysadmins to make this directory available via rsync.
1256
1dbf7599
DG
1257XXX Who are the sysadmins? Contact info?
1258
da571fa1 1259=for checklist skip BLEAD-POINT RC
d5722260 1260
f6b1864d 1261=head3 copy perldelta.pod to blead
addebd58 1262
6a958a95 1263I<You MUST SKIP this step for RC, BLEAD-POINT>
8c35d285 1264
f6b1864d 1265Copy the perldelta.pod for this release into blead; for example:
7277a900 1266
ed380305
KW
1267 $ cd ..../blead
1268 $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
1269 $ git add pod/perl5101delta.pod
75a012fe 1270
5d0d3de0
SH
1271Don't forget to set the NAME correctly in the new file (e.g. perl5101delta
1272rather than perldelta).
1273
0aef0fe5 1274Edit F<pod/perl.pod> to add an entry for the file, e.g.:
75a012fe
DM
1275
1276 perl5101delta Perl changes in version 5.10.1
bc4c40f2 1277
75a012fe 1278Then rebuild various files:
7277a900 1279
00b85c8d 1280 $ perl Porting/pod_rules.pl
75a012fe 1281
c90225ed 1282Finally, commit and push:
75a012fe
DM
1283
1284 $ git commit -a -m 'add perlXXXdelta'
c90225ed 1285 $ git push origin ....
dc0a4df9 1286
819435de 1287=for checklist skip BLEAD-POINT
7277a900 1288
819435de 1289=head3 copy perlhist.pod entries to blead
1dbf7599 1290
f6af4394 1291Make sure any recent F<pod/perlhist.pod> entries are copied to
80dd5f25 1292F<perlhist.pod> on blead. e.g.
7277a900 1293
f6af4394 1294 5.8.9 2008-Dec-14
7277a900 1295
dc0a4df9 1296=head3 bump RT version number
6e40fbf9 1297
7c139051 1298Log into http://rt.perl.org/ and check whether the new version is in the RT
1dbf7599
DG
1299fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is to
1300open up any ticket for modification and check the drop downs next to the
1301C<Perl Version> and C<Fixed In> labels.
7c139051 1302
1e5abc58 1303Here, try this link: L<https://rt.perl.org/Ticket/Modify.html?id=10000>
e290a61e 1304
7c139051
DR
1305If the new version is not listed there, send an email to C<perlbug-admin at
1306perl.org> requesting this.
dc0a4df9
DM
1307
1308=head3 Relax!
a3738a12 1309
bc4c40f2
JV
1310I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
1311much-needed rest and relaxation>.
8c35d285
JV
1312
1313Thanks for releasing perl!
1314
b28f69c2
Z
1315=head2 Building a release - the day after
1316
ab0bff1f 1317=for checklist skip BLEAD-FINAL, MAINT, RC
042e7a25 1318
ab0bff1f 1319=head3 update Module::CoreList
042e7a25
DG
1320
1321I<After a BLEAD-POINT release only>
1322
1323After Module::CoreList has shipped to CPAN by the maintainer, update
1324Module::CoreList in the source so that it reflects the new blead
ab0bff1f
SH
1325version number:
1326
1327=over 4
1328
1329=item *
1330
1331Update F<Porting/Maintainers.pl> to list the new DISTRIBUTION on CPAN,
1332which should be identical to what is currently in blead.
1333
1334=item *
1335
1336Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm>,
1337F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm> and
1338F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
1339
1340=item *
1341
1342If you have a local CPAN mirror, run:
1343
1344 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
1345
1346Otherwise, run:
1347
1348 $ ./perl -Ilib Porting/corelist.pl cpan
1349
244e6e4e
SH
1350This will update F<dist/Module-CoreList/lib/Module/CoreList.pm>,
1351F<dist/Module-CoreList/lib/Module/CoreList.pod> and
1352F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before,
1353but this time adding new sections for the next BLEAD-POINT release.
ab0bff1f
SH
1354
1355=item *
1356
1357Add the new $Module::CoreList::VERSION to
1358F<dist/Module-CoreList/Changes>.
1359
1360=item *
1361
1362Update F<pod/perldelta.pod> to mention the upgrade to Module::CoreList.
1363
1364=item *
1365
1366Remake perl to get your changed .pm files propagated into F<lib/> and
1367then run at least the F<dist/Module-CoreList/t/*.t> tests and the
1368test_porting makefile target to check that they're ok.
1369
1370=item *
1371
1372Run
1373
1374 $ ./perl -Ilib -MModule::CoreList -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
1375
1376and check that it outputs "ok" to prove that Module::CoreList now knows
1377about blead's current version.
1378
1379=item *
1380
1381Commit and push your changes.
1382
1383=back
042e7a25 1384
dc0a4df9
DM
1385=head3 check tarball availability
1386
1387Check various website entries to make sure the that tarball has appeared
1388and is properly indexed:
1389
b28f69c2
Z
1390=over 4
1391
1392=item *
1393
98df743a
Z
1394Check your author directory under L<http://www.cpan.org/authors/id/>
1395to ensure that the tarballs are available on the website.
b28f69c2
Z
1396
1397=item *
1398
98df743a 1399Check C</src> on CPAN (on a fast mirror) to ensure that links to
ac2aec01
SH
1400the new tarballs have appeared: There should be links in C</src/5.0>
1401(which is accumulating all new versions), and (for BLEAD-FINAL and
1402MAINT only) an appropriate mention in C</src/README.html> (which describes
1403the latest versions in each stable branch, with links).
98df743a 1404
1dbf7599 1405The C</src/5.0> links should appear automatically, some hours after upload.
02e2c3c0 1406If they don't, or the C</src> description is inadequate,
98df743a 1407ask Ask <ask@perl.org>.
b28f69c2
Z
1408
1409=item *
1410
98df743a
Z
1411Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
1412have been correctly mirrored to the website.
1413If they haven't, ask Ask <ask@perl.org>.
1414
1415=item *
b28f69c2 1416
98df743a
Z
1417Check L<http://search.cpan.org> to see if it has indexed the distribution.
1418It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
b28f69c2 1419
dc0a4df9 1420=back
b28f69c2 1421
e7b51df1 1422=for checklist skip RC
dc0a4df9
DM
1423
1424=head3 update dev.perl.org
1425
e7b51df1 1426I<You MUST SKIP this step for a RC release>
98df743a 1427
5fbaa27a 1428In your C<perlweb> repository, link to the new release. For a new
7a664ed5
RS
1429latest-maint release, edit F<docs/shared/tpl/stats.html>. Otherwise,
1430edit F<docs/dev/perl5/index.html>.
1431
1432Then make a pull request to Leo Lapworth. If this fails for some reason
1433and you cannot cajole anybody else into submitting that change, you can
1434mail Leo as last resort.
b28f69c2 1435
7dbb22ac
A
1436This repository can be found on L<github|https://github.com/perlorg/perlweb>.
1437
1dbf7599
DG
1438=head3 update release manager's guide
1439
1440Go over your notes from the release (you did take some, right?) and update
1441F<Porting/release_managers_guide.pod> with any fixes or information that
1442will make life easier for the next release manager.
1443
da571fa1 1444=for checklist end
b28f69c2 1445
7277a900
GS
1446=head1 SOURCE
1447
f6af4394
DM
1448Based on
1449http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
1450plus a whole bunch of other sources, including private correspondence.
7277a900
GS
1451
1452=cut
1453