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