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