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