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