This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
RMG - Update local_patches[] code snippet with current code
[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
78a62309
SH
18 perl Porting/make-rmg-checklist \
19 --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod
c78277ad
DR
20
21You can also pass the C<--html> flag to generate an HTML document instead of
22POD.
f6af4394 23
78a62309
SH
24 perl Porting/make-rmg-checklist --html \
25 --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html
0056d3d2 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
78a62309
SH
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)
ed380305 328
78a62309 329 attempt to group failure causes
ed380305 330
78a62309
SH
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
78a62309 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 390some of which need to be left unchanged.
2f05d209 391See below in L<"update INSTALL"> for more details.
e03f126c 392
cdf175f7
SH
393For the first RC release leading up to a BLEAD-FINAL release, update the
394description of which releases are now "officially" supported in
395F<pod/perlpolicy.pod>.
396
6a958a95
DM
397When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
398C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
ac2aec01
SH
399you're releasing, unless you're absolutely sure the release you're about to
400make is 100% binary compatible to an earlier release. When releasing a MAINT
401perl version, the C<PERL_API_*> constants C<MUST NOT> be changed as we aim
402to guarantee binary compatibility in maint branches.
45ce9531 403
17163f85
DM
404After editing, regenerate uconfig.h (this must be run on a system with a
405/bin/sh available):
22be9667 406
78a62309 407 $ perl regen/uconfig_h.pl
22be9667 408
78957677
JL
409This might not cause any new changes.
410
82ce0493
A
411You may also need to regen opcodes:
412
78a62309 413 $ ./perl -Ilib regen/opcode.pl
82ce0493 414
9a055687 415You may have to add stub entries in C<%Module::CoreList::version>,
82ce0493
A
416C<%Module::CoreList::deprecated> and C<%Module::CoreList::Utils::delta>.
417If so, you must up their version numbers as well.
418
22be9667
JV
419Test your changes:
420
78a62309
SH
421 $ git clean -xdf # careful if you don't have local files to keep!
422 $ ./Configure -des -Dusedevel
423 $ make
424 $ make test
22be9667 425
54356a6f
JV
426Commit your changes:
427
78a62309
SH
428 $ git status
429 $ git diff
430 B<review the delta carefully>
54356a6f 431
78a62309 432 $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
dc0a62a1 433
21768cb3 434At this point you may want to compare the commit with a previous bump to
ac2aec01 435see if they look similar. See commit f7cf42bb69 for an example of a
21768cb3
FC
436previous version bump.
437
dc0a4df9
DM
438When the version number is bumped, you should also update Module::CoreList
439(as described below in L<"update Module::CoreList">) to reflect the new
81fc59ef
DG
440version number.
441
dc0a4df9 442=head3 update INSTALL
dc0a62a1 443
2f05d209
SH
444Review and update INSTALL to account for the change in version number.
445The lines in F<INSTALL> about "is not binary compatible with" may require a
446correct choice of earlier version to declare incompatibility with. These are
447in the "Changes and Incompatibilities" and "Coexistence with earlier versions
448of perl 5" sections.
dc0a62a1 449
6a958a95
DM
450Be particularly careful with the section "Upgrading from 5.X.Y or earlier".
451The "X.Y" needs to be changed to the most recent version that we are
452I<not> binary compatible with.
453
454For MAINT and BLEAD-FINAL releases, this needs to refer to the last
455release in the previous development cycle (so for example, for a 5.14.x
456release, this would be 5.13.11).
457
458For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
459release (so for 5.15.3 this would be 5.15.2).
460
52d097d9
S
461=head3 Check copyright years
462
463Check that the copyright years are up to date by running:
464
78a62309 465 $ ./perl t/porting/copyright.t --now
52d097d9
S
466
467Remedy any test failures by editing README or perl.c accordingly (search for
468the "Copyright"). If updating perl.c, check if the file's own copyright date in
469the C comment at the top needs updating, as well as the one printed by C<-v>.
470
dc0a4df9 471=head3 Check more build configurations
b82efa27 472
d8fc5aa0
DR
473Try running the full test suite against multiple Perl configurations. Here are
474some sets of Configure flags you can try:
52a66c2c 475
d8fc5aa0 476=over 4
7277a900 477
d8fc5aa0
DR
478=item *
479
480C<-Duseshrplib -Dusesitecustomize>
481
482=item *
483
484C<-Duserelocatableinc>
485
486=item *
487
488C<-Dusethreads>
489
490=back
7277a900 491
d8fc5aa0
DR
492If you have multiple compilers on your machine, you might also consider
493compiling with C<-Dcc=$other_compiler>.
dc0a4df9
DM
494
495=head3 update perlport
7277a900 496
347f5124
RGS
497L<perlport> has a section currently named I<Supported Platforms> that
498indicates which platforms are known to build in the current release.
499If necessary update the list and the indicated version number.
500
1dbf7599
DG
501=head3 check a readonly build
502
503Even before other prep work, follow the steps in L<build the tarball> and test
504it locally. Because a perl source tarballs sets many files read-only, it could
505test differently than tests run from the repository. After you're sure
506permissions aren't a problem, delete the generated directory and tarballs.
6a958a95 507
2e831dfd
DM
508=head2 Building a release - on the day
509
b1288acc 510This section describes the actions required to make a release
f6b1864d 511that are performed near to, or on the actual release day.
2e831dfd 512
dc0a4df9 513=head3 re-check earlier actions
2e831dfd 514
dc0a4df9 515Review all the actions in the previous section,
2e831dfd
DM
516L<"Building a release - advance actions"> to ensure they are all done and
517up-to-date.
518
ff721450
JL
519=head3 create a release branch
520
521For BLEAD-POINT releases, making a release from a release branch avoids the
522need to freeze blead during the release. This is less important for
523BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in
524those cases. Create the branch by running
525
78a62309 526 git checkout -b release-5.xx.yy
ff721450 527
dc0a4df9 528=head3 build a clean perl
8c35d285 529
1dbf7599 530Make sure you have a gitwise-clean perl directory (no modified files,
a0db33fe 531unpushed commits etc):
8c35d285 532
a0db33fe 533 $ git status
24c5e187 534 $ git clean -dxf
8c35d285 535
dc0a4df9 536then configure and build perl so that you have a Makefile and porting tools:
8c35d285 537
52a66c2c 538 $ ./Configure -Dusedevel -des && make
8c35d285 539
a8ec9917
SH
540=head3 Check module versions
541
542For each Perl release since the previous release of the current branch, check
543for modules that have identical version numbers but different contents by
544running:
545
546 $ ./perl Porting/cmpVERSION.pl --tag=v5.X.YY
547
548(This is done automatically by F<t/porting/cmp_version.t> for the previous
549release of the current branch, but not for any releases from other branches.)
550
551Any modules that fail will need a version bump, plus a nudge to the upstream
552maintainer for 'cpan' upstream modules.
553
dc0a4df9 554=head3 update Module::CoreList
8c35d285 555
0429cb0e
SH
556=head4 Bump Module::CoreList* $VERSIONs
557
78a62309
SH
558If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this
559for every RC; in RC1, bump the version to a new clean number that will
0429cb0e
SH
560appear in the final release, and leave as-is for the later RCs and final).
561It may also happen that C<Module::CoreList> has been modified in blead, and
562hence has a new version number already. (But make sure it is not the same
563number as a CPAN release.)
564
565C<$Module::CoreList::TieHashDelta::VERSION> and
566C<$Module::CoreList::Utils::VERSION> should always be equal to
567C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match
568before proceeding.
569
5bbd8f61
A
570The files to modify are: F<dist/Module-CoreList/lib/Module/CoreList.pm>,
571F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> and
572F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm>.
94691c19 573
0429cb0e 574=head4 Update C<Module::CoreList> with module version data for the new release.
bfadf2ba 575
6a958a95 576Note that if this is a MAINT release, you should run the following actions
1bac61bb 577from the maint branch, but commit the C<CoreList.pm> changes in
a9d1f3db
LB
578I<blead> and subsequently cherry-pick any releases since the last
579maint release and then your recent commit. XXX need a better example
bfadf2ba 580
89781932
DM
581[ Note that the procedure for handling Module::CoreList in maint branches
582is a bit complex, and the RMG currently don't describe a full and
583workable approach. The main issue is keeping Module::CoreList
584and its version number synchronised across all maint branches, blead and
585CPAN, while having to bump its version number for every RC release.
586See this brief p5p thread:
587
588 Message-ID: <20130311174402.GZ2294@iabyn.com>
589
590If you can devise a workable system, feel free to try it out, and to
38e4b857 591update the RMG accordingly!
89781932
DM
592
593DAPM May 2013 ]
594
a0db33fe 595F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
218a07e7
SH
596modules on CPAN. It can use a full, local CPAN mirror and/or fall back
597on HTTP::Tiny to fetch package metadata remotely.
bfadf2ba 598
fdaa3f94 599(If you'd prefer to have a full CPAN mirror, see
bfadf2ba
JV
600http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
601
a0db33fe 602Then change to your perl checkout, and if necessary,
bfadf2ba 603
595f83ae 604 $ make
bfadf2ba 605
bf8ea215 606Then, If you have a local CPAN mirror, run:
bfadf2ba 607
bfadf2ba
JV
608 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
609
610Otherwise, run:
611
bfadf2ba
JV
612 $ ./perl -Ilib Porting/corelist.pl cpan
613
52a66c2c 614This will chug for a while, possibly reporting various warnings about
2a720090 615badly-indexed CPAN modules unrelated to the modules actually in core.
2ce7d676 616Assuming all goes well, it will update
ab0bff1f 617F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly
244e6e4e 618F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
bfadf2ba 619
ab0bff1f 620Check those files over carefully:
bfadf2ba 621
d5bddf6e 622 $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
244e6e4e 623 $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm
1dbf7599 624
00c28750
DR
625=head4 Bump version in Module::CoreList F<Changes>
626
0429cb0e 627Also edit Module::CoreList's new version number in its F<Changes> file.
e8c01f92 628
00c28750
DR
629=head4 Add Module::CoreList version bump to perldelta
630
70855f8b
FC
631Add a perldelta entry for the new Module::CoreList version.
632
da571fa1
DR
633=for checklist skip RC
634
09abf5f8 635=head4 Update C<%Module::CoreList::released>
da571fa1 636
09abf5f8
SH
637For any release except an RC: Update this version's entry in the C<%released>
638hash with today's date.
bfadf2ba 639
00c28750
DR
640=head4 Commit Module::CoreList changes
641
bfadf2ba 642Finally, commit the new version of Module::CoreList:
6a958a95 643(unless this is for MAINT; in which case commit it to blead first, then
a0db33fe 644cherry-pick it back).
bfadf2ba 645
78a62309
SH
646 $ git commit -m 'Update Module::CoreList for 5.x.y' \
647 dist/Module-CoreList/Changes \
648 dist/Module-CoreList/lib/Module/CoreList.pm \
649 dist/Module-CoreList/lib/Module/CoreList/Utils.pm
bfadf2ba 650
1dbf7599
DG
651=head4 Rebuild and test
652
78a62309
SH
653Build and test to get the changes into the currently built lib directory and to
654ensure all tests are passing.
1dbf7599
DG
655
656=head3 finalize perldelta
657
658Finalize the perldelta. In particular, fill in the Acknowledgements
659section, which can be generated with something like:
660
78a62309 661 $ perl Porting/acknowledgements.pl v5.15.0..HEAD
1dbf7599 662
78a62309
SH
663Fill in the "New/Updated Modules" sections now that Module::CoreList is
664updated:
2c5d738b 665
78a62309
SH
666 $ ./perl -Ilib Porting/corelist-perldelta.pl \
667 --mode=update pod/perldelta.pod
be2822b0
SH
668
669For a MAINT release use something like this instead:
670
78a62309
SH
671 $ ./perl -Ilib Porting/corelist-perldelta.pl 5.020001 5.020002 \
672 --mode=update pod/perldelta.pod
2c5d738b
SH
673
674Ideally, also fill in a summary of the major changes to each module for which
675an entry has been added by F<corelist-perldelta.pl>.
1dbf7599
DG
676
677Re-read the perldelta to try to find any embarrassing typos and thinkos;
678remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
679with any serious issues for which fixes are not going to happen now; and
680run through pod and spell checkers, e.g.
681
682 $ podchecker -warnings -warnings pod/perldelta.pod
683 $ spell pod/perldelta.pod
684
685Also, you may want to generate and view an HTML version of it to check
686formatting, e.g.
687
78a62309
SH
688 $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > \
689 /tmp/perldelta.html
1dbf7599
DG
690
691Another good HTML preview option is http://search.cpan.org/pod2html
692
693If you make changes, be sure to commit them.
694
695=for checklist skip BLEAD-POINT MAINT RC
696
697=head3 remove stale perldeltas
698
699For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
1f6591ac 700from the BLEAD-POINT releases since the previous BLEAD-FINAL should have
1dbf7599
DG
701now been consolidated into the current perldelta, and hence are now just
702useless clutter. They can be removed using:
703
704 $ git rm <file1> <file2> ...
705
706For example, for RC0 of 5.16.0:
707
708 $ cd pod
709 $ git rm perldelta515*.pod
710
1f6591ac 711=for checklist skip BLEAD-FINAL BLEAD-POINT
1dbf7599
DG
712
713=head3 add recent perldeltas
714
715For the first RC for a MAINT release, copy in any recent perldeltas from
716blead that have been added since the last release on this branch. This
717should include any recent maint releases on branches older than your one,
718but not newer. For example if you're producing a 5.14.x release, copy any
719perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from
7205.16.x or higher. Remember to
721
722 $ git add <file1> <file2> ...
723
724=head3 update and commit perldelta files
725
726If you have added or removed any perldelta files via the previous two
727steps, then edit F<pod/perl.pod> to add/remove them from its table of
728contents, then run F<Porting/pod_rules.pl> to propagate your changes there
729into all the other files that mention them (including F<MANIFEST>). You'll
730need to C<git add> the files that it changes.
731
732Then build a clean perl and do a full test
733
734 $ git status
735 $ git clean -dxf
736 $ ./Configure -Dusedevel -des
737 $ make
738 $ make test
739
740Once all tests pass, commit your changes.
741
742=head3 build a clean perl
743
744If you skipped the previous step (adding/removing perldeltas),
745again, make sure you have a gitwise-clean perl directory (no modified files,
746unpushed commits etc):
747
748 $ git status
749 $ git clean -dxf
750
751then configure and build perl so that you have a Makefile and porting tools:
752
753 $ ./Configure -Dusedevel -des && make
754
1f6591ac 755=for checklist skip BLEAD-FINAL BLEAD-POINT
80dd5f25
DM
756
757=head3 synchronise from blead's perlhist.pod
758
759For the first RC for a MAINT release, copy in the latest
760F<pod/perlhist.pod> from blead; this will include details of newer
761releases in all branches. In theory, blead's version should be a strict
762superset of the one in this branch, but it's probably safest to diff them
763first to ensure that there's nothing in this branch that was forgotten
764from blead:
765
766 $ diff pod/perlhist.pod ..../blead/pod/perlhist.pod
767 $ cp ..../blead/pod/perlhist.pod pod/
768 $ git commit -m 'sync perlhist from blead' pod/perlhist.pod
769
dc0a4df9 770=head3 update perlhist.pod
a0db33fe 771
e8a7a70e
JV
772Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
773
774 David 5.10.1 2009-Aug-06
a0db33fe 775
a420fd35
MH
776List yourself in the left-hand column, and if this is the first release
777that you've ever done, make sure that your name is listed in the section
778entitled C<THE KEEPERS OF THE PUMPKIN>.
a0db33fe 779
56e2d9fb 780I<If you're making a BLEAD-FINAL release>, also update the "SELECTED
bd4ce907
RS
781RELEASE SIZES" section with the output of
782F<Porting/perlhist_calculate.pl>.
783
a0db33fe
DM
784Be sure to commit your changes:
785
786 $ git commit -m 'add new release to perlhist' pod/perlhist.pod
8c35d285 787
da571fa1 788=for checklist skip BLEAD-POINT
dc0a4df9
DM
789
790=head3 update patchlevel.h
8c35d285 791
6a958a95 792I<You MUST SKIP this step for a BLEAD-POINT release>
d7eb1120 793
a42352ee
DM
794Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
795a final release, remove it. For example:
d7eb1120
DM
796
797 static const char * const local_patches[] = {
798 NULL
799 + ,"RC1"
0bf51988
SH
800 #ifdef PERL_GIT_UNCOMMITTED_CHANGES
801 ,"uncommitted-changes"
802 #endif
d7eb1120
DM
803
804Be sure to commit your change:
805
806 $ git commit -m 'bump version to RCnnn' patchlevel.h
807
4612967b
CBW
808=head3 run makemeta to update META files
809
e4fbed99 810 $ ./perl -Ilib Porting/makemeta
4612967b
CBW
811
812Be sure to commit any changes (if applicable):
813
e4fbed99 814 $ git status # any changes?
4612967b 815 $ git commit -m 'Update META files' META.*
dc0a4df9
DM
816
817=head3 build, test and check a fresh perl
d7eb1120 818
a0db33fe
DM
819Build perl, then make sure it passes its own test suite, and installs:
820
821 $ git clean -xdf
a42352ee
DM
822 $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
823
824 # or if it's an odd-numbered version:
a0db33fe 825 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
a42352ee 826
a0db33fe
DM
827 $ make test install
828
52a66c2c
DM
829Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
830C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
a0db33fe 831especially as regards version numbers, patch and/or RC levels, and @INC
c5fb089a 832paths. Note that as they have been built from a git working
52a66c2c 833directory, they will still identify themselves using git tags and
01725c10
A
834commits. (Note that for an odd-numbered version, perl will install
835itself as C<perl5.x.y>). C<perl -v> will identify itself as:
836
78a62309 837 This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))
01725c10 838
78957677 839where 5.X.Z is the latest tag, NNN the number of commits since this tag,
01725c10 840and C<< deadbeef >> commit of that tag.
52a66c2c
DM
841
842Then delete the temporary installation.
843
c90225ed 844=head3 create the release tag
dc0a4df9 845
c90225ed 846Create the tag identifying this release (e.g.):
96054f12 847
b6d23947 848 $ git tag v5.11.0 -m "First release of the v5.11 series!"
e8c01f92 849
6a958a95 850It is B<VERY> important that from this point forward, you not push
f662f3b7
JV
851your git changes to the Perl master repository. If anything goes
852wrong before you publish your newly-created tag, you can delete
853and recreate it. Once you push your tag, we're stuck with it
854and you'll need to use a new version number for your release.
855
dc0a4df9 856=head3 build the tarball
a0db33fe 857
0dcf3caa 858Before you run the following, you might want to install 7-Zip (the
0dcb816b 859C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or
0dcf3caa
LB
860the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian,
861or the C<advancecomp> port on macports - 7-Zip on Windows is the
862same code as AdvanceCOMP, so Windows users get the smallest files
863first time). These compress about 5% smaller than gzip and bzip2.
864Over the lifetime of your distribution this will save a lot of
865people a small amount of download time and disk space, which adds
866up.
867
2174049d
CBW
868In order to produce the C<xz> tarball, XZ Utils are required. The C<xz>
869utility is included with most modern UNIX-type operating systems and
870is available for Cygwin. A Windows port is available from
871L<http://tukaani.org/xz/>.
872
8c35d285
JV
873Create a tarball. Use the C<-s> option to specify a suitable suffix for
874the tarball and directory name:
875
78a62309
SH
876 $ cd root/of/perl/tree
877 $ make distclean # make sure distclean works
878 $ git clean -xdf # make sure perl and git agree on files
879 # git clean should not output anything!
880 $ git status # and there's nothing lying around
8c35d285 881
78a62309
SH
882 $ perl Porting/makerel -bx -s RC1 # for a release candidate
883 $ perl Porting/makerel -bx # for a final release
8c35d285
JV
884
885This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
ac2aec01
SH
886the MANIFEST files into it, sets the correct permissions on them, then
887tars it up as F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a
2174049d 888C<tar.bz2> file. The C<-x> also produces a C<tar.xz> file.
8c35d285 889
6480287f
MT
890If you're getting your tarball suffixed with -uncommitted and you're sure
891your changes were all committed, you can override the suffix with:
892
893 $ perl Porting/makerel -b -s ''
96054f12 894
8c35d285
JV
895XXX if we go for extra tags and branches stuff, then add the extra details
896here
897
dc0a4df9 898Finally, clean up the temporary directory, e.g.
a42352ee
DM
899
900 $ rm -rf ../perl-x.y.z-RC1
901
dc0a4df9
DM
902=head3 test the tarball
903
00c28750 904Once you have a tarball it's time to test the tarball (not the repository).
dc0a4df9 905
00c28750 906=head4 Copy the tarball to a web server
a42352ee 907
2174049d 908Copy the tarballs (.gz and possibly .bz2 and .xz) to a web server somewhere you
8c35d285
JV
909have access to.
910
00c28750 911=head4 Download the tarball to another machine
8c35d285 912
fdaa3f94 913Download the tarball to some other machine. For a release candidate,
8c35d285
JV
914you really want to test your tarball on two or more different platforms
915and architectures. The #p5p IRC channel on irc.perl.org is a good place
916to find willing victims.
917
00c28750 918=head4 Check that F<Configure> works
8c35d285
JV
919
920Check that basic configuration and tests work on each test machine:
921
e07c44df
MH
922 $ ./Configure -des && make all test
923
924 # Or for a development release:
bf8aad21 925 $ ./Configure -Dusedevel -des && make all test
f6af4394 926
00c28750 927=head4 Run the test harness and install
f6af4394 928
8c35d285
JV
929Check that the test harness and install work on each test machine:
930
a42352ee 931 $ make distclean
8c35d285 932 $ ./Configure -des -Dprefix=/install/path && make all test_harness install
a42352ee 933 $ cd /install/path
8c35d285 934
00c28750 935=head4 Check C<perl -v> and C<perl -V>
8c35d285
JV
936
937Check that the output of C<perl -v> and C<perl -V> are as expected,
938especially as regards version numbers, patch and/or RC levels, and @INC
fdaa3f94 939paths.
8c35d285
JV
940
941Note that the results may be different without a F<.git/> directory,
942which is why you should test from the tarball.
943
00c28750 944=head4 Run the Installation Verification Procedure utility
459fc3ca 945
9651cacc 946 $ ./perl utils/perlivp
459fc3ca
DM
947 ...
948 All tests successful.
949 $
950
00c28750 951=head4 Compare the installed paths to the last release
459fc3ca 952
d60a1044
DM
953Compare the pathnames of all installed files with those of the previous
954release (i.e. against the last installed tarball on this branch which you
955have previously verified using this same procedure). In particular, look
956for files in the wrong place, or files no longer included which should be.
957For example, suppose the about-to-be-released version is 5.10.1 and the
958previous is 5.10.0:
959
960 cd installdir-5.10.0/
961 find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
962 cd installdir-5.10.1/
963 find . -type f | sort > /tmp/f2
964 diff -u /tmp/f[12]
965
29205e9c 966=head4 Bootstrap the CPAN client
d60a1044 967
8c35d285
JV
968Bootstrap the CPAN client on the clean install:
969
29205e9c 970 $ bin/cpan
8c35d285 971
61a1ab54
MH
972 # Or, perhaps:
973 $ bin/cpan5.xx.x
974
29205e9c 975=head4 Install the Inline module with CPAN and test it
8c35d285 976
a42352ee
DM
977Try installing a popular CPAN module that's reasonably complex and that
978has dependencies; for example:
8c35d285 979
65651c62 980 CPAN> install Inline::C
a42352ee 981 CPAN> quit
8c35d285
JV
982
983Check that your perl can run this:
984
16c60e4e 985 $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
a42352ee
DM
986 42
987 $
8c35d285 988
00c28750 989=head4 Make sure that perlbug works
8c35d285 990
00c28750 991Test L<perlbug> with the following:
47b1f096 992
a14438df 993 $ bin/perlbug
47b1f096
DM
994 ...
995 Subject: test bug report
fdaa3f94
CBW
996 Local perl administrator [yourself]:
997 Editor [vi]:
998 Module:
999 Category [core]:
1000 Severity [low]:
47b1f096
DM
1001 (edit report)
1002 Action (Send/Display/Edit/Subject/Save to File): f
fdaa3f94 1003 Name of file to save message in [perlbug.rep]:
47b1f096
DM
1004 Action (Send/Display/Edit/Subject/Save to File): q
1005
1006and carefully examine the output (in F<perlbug.rep]>), especially
1007the "Locally applied patches" section. If everything appears okay, then
75a012fe
DM
1008delete the file, and try it again, this time actually submitting the bug
1009report. Check that it shows up, then remember to close it!
47b1f096 1010
da571fa1 1011=for checklist skip BLEAD-POINT
dc0a4df9
DM
1012
1013=head3 monitor smokes
47b1f096 1014
1dbf7599
DG
1015XXX This is probably irrelevant if working on a release branch, though
1016MAINT or RC might want to push a smoke branch and wait.
1017
f6af4394
DM
1018Wait for the smoke tests to catch up with the commit which this release is
1019based on (or at least the last commit of any consequence).
7277a900 1020
f6af4394
DM
1021Then check that the smoke tests pass (particularly on Win32). If not, go
1022back and fix things.
7277a900 1023
6a958a95 1024Note that for I<BLEAD-POINT> releases this may not be practical. It takes a
1eefd7d5 1025long time for the smokers to catch up, especially the Win32
6a958a95
DM
1026smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL>
1027releases, but for I<BLEAD-POINT> releases sometimes the best you can do is
1028to plead with people on IRC to test stuff on their platforms, fire away,
1029and then hope for the best.
7277a900 1030
dc0a4df9 1031=head3 upload to PAUSE
7277a900 1032
f6af4394 1033Once smoking is okay, upload it to PAUSE. This is the point of no return.
db3f805e
JV
1034If anything goes wrong after this point, you will need to re-prepare
1035a new release with a new minor version or RC number.
1036
a14438df
DM
1037 https://pause.perl.org/
1038
1039(Login, then select 'Upload a file to CPAN')
1040
45924287
RS
1041If your workstation is not connected to a high-bandwidth,
1042high-reliability connection to the Internet, you should probably use the
1043"GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
1044new release from wherever you put it for testers to find it. This will
1045eliminate anxious gnashing of teeth while you wait to see if your
104615 megabyte HTTP upload successfully completes across your slow, twitchy
c27b4e97
SH
1047cable modem. You can make use of your home directory on dromedary for
1048this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
1049F</home/USERNAME/public_html>, where F<USERNAME> is your login account
1050on dromedary. I<Remember>: if your upload is partially successful, you
1051may need to contact a PAUSE administrator or even bump the version of perl.
45924287 1052
5cd8f091 1053Upload the .gz, .xz, and .bz2 versions of the tarball.
f6af4394 1054
1dbf7599
DG
1055Do not proceed any further until you are sure that your tarballs are on CPAN.
1056Check your authors directory www.cpan.org (the globally balanced "fast"
1057mirror) to confirm that your uploads have been successful.
c27b4e97 1058
1dbf7599 1059=for checklist skip RC BLEAD-POINT
00c28750
DR
1060
1061=head3 wait for indexing
1062
1dbf7599 1063I<You MUST SKIP this step for RC and BLEAD-POINT>
76526317
FR
1064
1065Wait until you receive notification emails from the PAUSE indexer
1066confirming that your uploads have been received. IMPORTANT -- you will
1067probably get an email that indexing has failed, due to module permissions.
1068This is considered normal.
1069
da571fa1 1070=for checklist skip BLEAD-POINT
dc0a4df9
DM
1071
1072=head3 disarm patchlevel.h
f6af4394 1073
6a958a95 1074I<You MUST SKIP this step for BLEAD-POINT release>
113f3f4c 1075
a42352ee 1076Disarm the F<patchlevel.h> change; for example,
d7eb1120
DM
1077
1078 static const char * const local_patches[] = {
1079 NULL
1080 - ,"RC1"
0bf51988
SH
1081 #ifdef PERL_GIT_UNCOMMITTED_CHANGES
1082 ,"uncommitted-changes"
1083 #endif
d7eb1120
DM
1084
1085Be sure to commit your change:
1086
1087 $ git commit -m 'disarm RCnnn bump' patchlevel.h
dc0a4df9
DM
1088
1089=head3 announce to p5p
2e831dfd 1090
db3f805e 1091Mail p5p to announce your new release, with a quote you prepared earlier.
f6af4394 1092
098d30ef 1093Use the template at Porting/release_announcement_template.txt
dc0a4df9 1094
a8cecd9d
RS
1095Send a carbon copy to C<noc@metacpan.org>
1096
ff721450
JL
1097=head3 merge release branch back to blead
1098
c90225ed 1099Merge the (local) release branch back into master now, and delete it.
ff721450 1100
78a62309
SH
1101 git checkout blead
1102 git pull
1103 git merge release-5.xx.yy
1104 git push
1105 git branch -d release-5.xx.yy
ff721450 1106
121e9ff0
SH
1107Note: The merge will create a merge commit if other changes have been pushed
1108to blead while you've been working on your release branch. Do NOT rebase your
1109branch to avoid the merge commit (as you might normally do when merging a
1110small branch into blead) since doing so will invalidate the tag that you
1111created earlier.
1112
c90225ed
SH
1113=head3 publish the release tag
1114
1115Now that you've shipped the new perl release to PAUSE and pushed your changes
1116to the Perl master repository, it's time to publish the tag you created
1117earlier too (e.g.):
1118
1119 $ git push origin tag v5.11.0
1120
dc0a4df9 1121=head3 update epigraphs.pod
f6af4394 1122
85531b0a 1123Add your quote to F<Porting/epigraphs.pod> and commit it.
70d95cc9
SH
1124You can include the customary link to the release announcement even before your
1125message reaches the web-visible archives by looking for the X-List-Archive
1126header in your message after receiving it back via perl5-porters.
dc0a4df9 1127
b02b3ec7
DR
1128=head3 blog about your epigraph
1129
1130If you have a blog, please consider writing an entry in your blog explaining
1131why you chose that particular quote for your epigraph.
1132
da571fa1
DR
1133=for checklist skip RC
1134
d274ee9d
SH
1135=head3 Release schedule
1136
1137I<You MUST SKIP this step for RC>
1138
1139Tick the entry for your release in F<Porting/release_schedule.pod>.
1140
1141=for checklist skip RC
1142
dc0a4df9 1143=head3 Module::CoreList nagging
85531b0a 1144
bc4c40f2 1145I<You MUST SKIP this step for RC>
8c35d285 1146
75a012fe
DM
1147Remind the current maintainer of C<Module::CoreList> to push a new release
1148to CPAN.
7277a900 1149
da571fa1 1150=for checklist skip RC
dc0a4df9
DM
1151
1152=head3 new perldelta
a2cba4bc 1153
bc4c40f2 1154I<You MUST SKIP this step for RC>
7277a900 1155
bcfe7366 1156Create a new perldelta.
5ef3945b 1157
bcfe7366 1158=over 4
8e967a1c 1159
bcfe7366 1160=item *
8e967a1c 1161
bcfe7366 1162Confirm that you have a clean checkout with no local changes.
c5b87fed 1163
bcfe7366 1164=item *
17163f85 1165
bcfe7366 1166Run F<Porting/new-perldelta.pl>
8e967a1c 1167
bcfe7366 1168=item *
17163f85 1169
bcfe7366 1170Run the C<git add> commands it outputs to add new and modified files.
7277a900 1171
bcfe7366 1172=item *
7277a900 1173
bcfe7366 1174Verify that the build still works, by running C<./Configure> and
e0373c35 1175C<make test_porting>. (On Win32 use the appropriate make utility).
17163f85 1176
bcfe7366 1177=item *
17163f85 1178
bcfe7366
NC
1179If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>,
1180run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail.
1181Skip to the end of its test output to see the options it offers you.
57433fbf 1182
bcfe7366 1183=item *
75a012fe 1184
bcfe7366 1185When C<make test_porting> passes, commit the new perldelta.
75a012fe 1186
bcfe7366 1187=back
75a012fe 1188
21768cb3 1189At this point you may want to compare the commit with a previous bump to
ac2aec01 1190see if they look similar. See commit ba03bc34a4 for an example of a
75a012fe 1191previous version bump.
57433fbf 1192
30f926b5 1193=for checklist skip MAINT RC
dc0a4df9
DM
1194
1195=head3 bump version
57433fbf 1196
30f926b5 1197I<You MUST SKIP this step for RC and MAINT>
dc0a62a1 1198
6a958a95
DM
1199If this was a BLEAD-FINAL release (i.e. the first release of a new maint
1200series, 5.x.0 where x is even), then bump the version in the blead branch
1201in git, e.g. 5.12.0 to 5.13.0.
17163f85 1202
6d5e92cd
FC
1203First, add a new feature bundle to F<regen/feature.pl>, initially by just
1204copying the exiting entry, and bump the file's $VERSION (after the __END__
1205marker); e.g.
17163f85
DM
1206
1207 "5.14" => [qw(switch say state unicode_strings)],
1208 + "5.15" => [qw(switch say state unicode_strings)],
addebd58 1209
57fef7cc
FC
1210Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>.
1211
dc0a4df9
DM
1212Then follow the section L<"Bump the version number"> to bump the version
1213in the remaining files and test and commit.
17163f85 1214
30f926b5
JL
1215If this was a BLEAD-POINT release, then just follow the section
1216L<"Bump the version number">.
1217
2136887a
DG
1218After bumping the version, follow the section L<"update INSTALL"> to
1219ensure all version number references are correct.
17163f85 1220
5f9f8ddf
SH
1221(Note: The version is NOT bumped immediately after a MAINT release in order
1222to avoid confusion and wasted time arising from bug reports relating to
1223"intermediate versions" such as 5.20.1-and-a-bit: If the report is caused
1224by a bug that gets fixed in 5.20.2 and this intermediate version already
1225calls itself 5.20.2 then much time can be wasted in figuring out why there
1226is a failure from something that "should have been fixed". If the bump is
1227late then there is a much smaller window of time for such confusing bug
1228reports to arise. (The opposite problem -- trying to figure out why there
1229*is* a bug in something calling itself 5.20.1 when in fact the bug was
1230introduced later -- shouldn't arise for MAINT releases since they should,
1231in theory, only contain bug fixes but never regressions.))
1232
d5c37431
NC
1233=head3 clean build and test
1234
1235Run a clean build and test to make sure nothing obvious is broken.
1236
1237In particular, F<Porting/perldelta_template.pod> is intentionally exempted
1238from podchecker tests, to avoid false positives about placeholder text.
1239However, once it's copied to F<pod/perldelta.pod> the contents can now
5cd8f091 1240cause test failures. Problems should be resolved by doing one of the
ef4474b5
KW
1241following:
1242
1243=over
1244
1245=item 1
1246
1247Replace placeholder text with correct text.
1248
1249=item 2
1250
1251If the problem is from a broken placeholder link, you can add it to the
1252array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines
1253containing such links should be marked with C<XXX> so that they get
1254cleaned up before the next release.
1255
1256=item 3
1257
1258Following the instructions output by F<t/porting/podcheck.t> on how to
1259update its exceptions database.
1260
1261=back
d5c37431 1262
dc0a4df9
DM
1263=head3 push commits
1264
1265Finally, push any commits done above.
1266
1267 $ git push origin ....
1268
da571fa1 1269=for checklist skip BLEAD-POINT MAINT RC
dc0a4df9
DM
1270
1271=head3 create maint branch
17163f85 1272
6a958a95 1273I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
17163f85 1274
6a958a95
DM
1275If this was a BLEAD-FINAL release (i.e. the first release of a new maint
1276series, 5.x.0 where x is even), then create a new maint branch based on
1277the commit tagged as the current release.
7277a900 1278
233ca920
JV
1279Assuming you're using git 1.7.x or newer:
1280
17163f85 1281 $ git checkout -b maint-5.12 v5.12.0
233ca920 1282 $ git push origin -u maint-5.12
addebd58 1283
dc0a4df9 1284
da571fa1
DR
1285=for checklist skip BLEAD-POINT MAINT RC
1286
d5722260
DK
1287=head3 make the maint branch available in the APC
1288
1289Clone the new branch into /srv/gitcommon/branches on camel so the APC will
1290receive its changes.
1291
07697565 1292 $ git clone --branch maint-5.14 /gitroot/perl.git \
d5722260 1293 ? /srv/gitcommon/branches/perl-5.14.x
07697565 1294 $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x
d5722260
DK
1295
1296And nag the sysadmins to make this directory available via rsync.
1297
1dbf7599
DG
1298XXX Who are the sysadmins? Contact info?
1299
da571fa1 1300=for checklist skip BLEAD-POINT RC
d5722260 1301
f6b1864d 1302=head3 copy perldelta.pod to blead
addebd58 1303
6a958a95 1304I<You MUST SKIP this step for RC, BLEAD-POINT>
8c35d285 1305
f6b1864d 1306Copy the perldelta.pod for this release into blead; for example:
7277a900 1307
78a62309
SH
1308 $ cd ..../blead
1309 $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
1310 $ git add pod/perl5101delta.pod
75a012fe 1311
5d0d3de0
SH
1312Don't forget to set the NAME correctly in the new file (e.g. perl5101delta
1313rather than perldelta).
1314
0aef0fe5 1315Edit F<pod/perl.pod> to add an entry for the file, e.g.:
75a012fe
DM
1316
1317 perl5101delta Perl changes in version 5.10.1
bc4c40f2 1318
75a012fe 1319Then rebuild various files:
7277a900 1320
00b85c8d 1321 $ perl Porting/pod_rules.pl
75a012fe 1322
c90225ed 1323Finally, commit and push:
75a012fe
DM
1324
1325 $ git commit -a -m 'add perlXXXdelta'
c90225ed 1326 $ git push origin ....
dc0a4df9 1327
819435de 1328=for checklist skip BLEAD-POINT
7277a900 1329
819435de 1330=head3 copy perlhist.pod entries to blead
1dbf7599 1331
f6af4394 1332Make sure any recent F<pod/perlhist.pod> entries are copied to
80dd5f25 1333F<perlhist.pod> on blead. e.g.
7277a900 1334
78a62309 1335 5.8.9 2008-Dec-14
7277a900 1336
dc0a4df9 1337=head3 bump RT version number
6e40fbf9 1338
7c139051 1339Log into http://rt.perl.org/ and check whether the new version is in the RT
1dbf7599
DG
1340fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is to
1341open up any ticket for modification and check the drop downs next to the
1342C<Perl Version> and C<Fixed In> labels.
7c139051 1343
1e5abc58 1344Here, try this link: L<https://rt.perl.org/Ticket/Modify.html?id=10000>
e290a61e 1345
7c139051
DR
1346If the new version is not listed there, send an email to C<perlbug-admin at
1347perl.org> requesting this.
dc0a4df9
DM
1348
1349=head3 Relax!
a3738a12 1350
bc4c40f2
JV
1351I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
1352much-needed rest and relaxation>.
8c35d285
JV
1353
1354Thanks for releasing perl!
1355
b28f69c2
Z
1356=head2 Building a release - the day after
1357
ab0bff1f 1358=for checklist skip BLEAD-FINAL, MAINT, RC
042e7a25 1359
ab0bff1f 1360=head3 update Module::CoreList
042e7a25
DG
1361
1362I<After a BLEAD-POINT release only>
1363
1364After Module::CoreList has shipped to CPAN by the maintainer, update
1365Module::CoreList in the source so that it reflects the new blead
ab0bff1f
SH
1366version number:
1367
1368=over 4
1369
1370=item *
1371
1372Update F<Porting/Maintainers.pl> to list the new DISTRIBUTION on CPAN,
1373which should be identical to what is currently in blead.
1374
1375=item *
1376
1377Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm>,
1378F<dist/Module-CoreList/lib/Module/CoreList/TieHashDelta.pm> and
1379F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>.
1380
1381=item *
1382
1383If you have a local CPAN mirror, run:
1384
1385 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
1386
1387Otherwise, run:
1388
1389 $ ./perl -Ilib Porting/corelist.pl cpan
1390
a4a5107a 1391This will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and
244e6e4e
SH
1392F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before,
1393but this time adding new sections for the next BLEAD-POINT release.
ab0bff1f
SH
1394
1395=item *
1396
1397Add the new $Module::CoreList::VERSION to
1398F<dist/Module-CoreList/Changes>.
1399
1400=item *
1401
1402Update F<pod/perldelta.pod> to mention the upgrade to Module::CoreList.
1403
1404=item *
1405
1406Remake perl to get your changed .pm files propagated into F<lib/> and
1407then run at least the F<dist/Module-CoreList/t/*.t> tests and the
1408test_porting makefile target to check that they're ok.
1409
1410=item *
1411
1412Run
1413
78a62309
SH
1414 $ ./perl -Ilib -MModule::CoreList \
1415 -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"'
ab0bff1f
SH
1416
1417and check that it outputs "ok" to prove that Module::CoreList now knows
1418about blead's current version.
1419
1420=item *
1421
1422Commit and push your changes.
1423
1424=back
042e7a25 1425
dc0a4df9
DM
1426=head3 check tarball availability
1427
1428Check various website entries to make sure the that tarball has appeared
1429and is properly indexed:
1430
b28f69c2
Z
1431=over 4
1432
1433=item *
1434
98df743a
Z
1435Check your author directory under L<http://www.cpan.org/authors/id/>
1436to ensure that the tarballs are available on the website.
b28f69c2
Z
1437
1438=item *
1439
98df743a 1440Check C</src> on CPAN (on a fast mirror) to ensure that links to
ac2aec01
SH
1441the new tarballs have appeared: There should be links in C</src/5.0>
1442(which is accumulating all new versions), and (for BLEAD-FINAL and
1443MAINT only) an appropriate mention in C</src/README.html> (which describes
1444the latest versions in each stable branch, with links).
98df743a 1445
1dbf7599 1446The C</src/5.0> links should appear automatically, some hours after upload.
02e2c3c0 1447If they don't, or the C</src> description is inadequate,
98df743a 1448ask Ask <ask@perl.org>.
b28f69c2
Z
1449
1450=item *
1451
98df743a
Z
1452Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
1453have been correctly mirrored to the website.
1454If they haven't, ask Ask <ask@perl.org>.
1455
1456=item *
b28f69c2 1457
98df743a
Z
1458Check L<http://search.cpan.org> to see if it has indexed the distribution.
1459It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
b28f69c2 1460
dc0a4df9 1461=back
b28f69c2 1462
e7b51df1 1463=for checklist skip RC
dc0a4df9
DM
1464
1465=head3 update dev.perl.org
1466
e7b51df1 1467I<You MUST SKIP this step for a RC release>
98df743a 1468
5fbaa27a 1469In your C<perlweb> repository, link to the new release. For a new
7a664ed5
RS
1470latest-maint release, edit F<docs/shared/tpl/stats.html>. Otherwise,
1471edit F<docs/dev/perl5/index.html>.
1472
1473Then make a pull request to Leo Lapworth. If this fails for some reason
1474and you cannot cajole anybody else into submitting that change, you can
1475mail Leo as last resort.
b28f69c2 1476
7dbb22ac
A
1477This repository can be found on L<github|https://github.com/perlorg/perlweb>.
1478
1dbf7599
DG
1479=head3 update release manager's guide
1480
1481Go over your notes from the release (you did take some, right?) and update
1482F<Porting/release_managers_guide.pod> with any fixes or information that
1483will make life easier for the next release manager.
1484
da571fa1 1485=for checklist end
b28f69c2 1486
7277a900
GS
1487=head1 SOURCE
1488
f6af4394
DM
1489Based on
1490http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
1491plus a whole bunch of other sources, including private correspondence.
7277a900
GS
1492
1493=cut
1494