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