This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Only describe the inplace mode of Porting/bump-perl-version in Porting/release_manage...
[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
f6af4394 10
7277a900
GS
11=head1 SYNOPSIS
12
f6af4394 13This document describes the series of tasks required - some automatic, some
dc0a4df9
DM
14manual - to produce a perl release of some description, be that a release
15candidate, or final, numbered release of maint or blead.
f6af4394 16
8c35d285 17The release process has traditionally been executed by the current
ee76d676
JV
18pumpking. Blead releases from 5.11.0 forward are made each month on the
1920th by a non-pumpking release engineer. The release engineer roster
20and schedule can be found in Porting/release_schedule.pod.
7277a900 21
8c35d285
JV
22This document both helps as a check-list for the release engineer
23and is a base for ideas on how the various tasks could be automated
24or distributed.
7277a900 25
636a1918 26The outline of a typical release cycle is as follows:
f6af4394 27
636a1918 28 (5.10.1 is released, and post-release actions have been done)
f6af4394
DM
29
30 ...time passes...
31
f6af4394
DM
32 a few weeks before the release, a number of steps are performed,
33 including bumping the version to 5.10.2
636a1918
DM
34
35 ...a few weeks passes...
46743ef7 36
f6af4394
DM
37 perl-5.10.2-RC1 is released
38
39 perl-5.10.2 is released
40
41 post-release actions are performed, including creating new
c5b87fed 42 perldelta.pod
f6af4394
DM
43
44 ... the cycle continues ...
7277a900 45
dc0a4df9 46
7277a900
GS
47=head1 DETAILS
48
6a958a95
DM
49Some of the tasks described below apply to all four types of
50release of Perl. (blead, RC, final release of maint, final
8c35d285
JV
51release of blead). Some of these tasks apply only to a subset
52of these release types. If a step does not apply to a given
53type of release, you will see a notation to that effect at
54the beginning of the step.
55
dc0a4df9 56
8c35d285
JV
57=head2 Release types
58
59=over 4
60
8c35d285
JV
61=item Release Candidate (RC)
62
d60a1044
DM
63A release candidate is an attempt to produce a tarball that is a close as
64possible to the final release. Indeed, unless critical faults are found
65during the RC testing, the final release will be identical to the RC
66barring a few minor fixups (updating the release date in F<perlhist.pod>,
67removing the RC status from F<patchlevel.h>, etc). If faults are found,
68then the fixes should be put into a new release candidate, never directly
69into a final release.
8c35d285 70
6a958a95
DM
71
72=item Stable/Maint release (MAINT).
73
74A release with an even version number, and subversion number > 0, such as
755.14.1 or 5.14.2.
8c35d285
JV
76
77At this point you should have a working release candidate with few or no
78changes since.
79
80It's essentially the same procedure as for making a release candidate, but
81with a whole bunch of extra post-release steps.
82
6a958a95
DM
83=item A blead point release (BLEAD-POINT)
84
85A release with an odd version number, such as 5.15.0 or 5.15.1.
86
87This isn't for production, so it has less stability requirements than for
88other release types, and isn't preceded by RC releases. Other than that,
89it is similar to a MAINT release.
90
91=item Blead final release (BLEAD-FINAL)
92
93A release with an even version number, and subversion number == 0, such as
dc0a4df9 945.14.0. That is to say, it's the big new release once per year.
8c35d285
JV
95
96It's essentially the same procedure as for making a release candidate, but
6a958a95 97with a whole bunch of extra post-release steps, even more than for MAINT.
8c35d285
JV
98
99=back
7277a900 100
dc0a4df9 101
fd838dcf
JV
102=head2 Prerequisites
103
104Before you can make an official release of perl, there are a few
105hoops you need to jump through:
106
107=over 4
108
8c35d285
JV
109=item PAUSE account
110
fd838dcf
JV
111Make sure you have a PAUSE account suitable for uploading a perl release.
112If you don't have a PAUSE account, then request one:
113
114 https://pause.perl.org/pause/query?ACTION=request_id
115
9a3b7d40
FR
116Check that your account is allowed to upload perl distros: go to
117L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that
118your PAUSE ID is listed there. If not, ask Andreas KE<0xf6>nig to add your ID
119to the list of people allowed to upload something called perl. You can find
120Andreas' email address at:
4d2c8158 121
fd838dcf
JV
122 https://pause.perl.org/pause/query?ACTION=pause_04imprint
123
fdabea7a
JV
124=item search.cpan.org
125
126Make sure that search.cpan.org knows that you're allowed to upload
127perl distros. Contact Graham Barr to make sure that you're on the right
128list.
129
8c35d285
JV
130=item CPAN mirror
131
132Some release engineering steps require a full mirror of the CPAN.
133Work to fall back to using a remote mirror via HTTP is incomplete
134but ongoing. (No, a minicpan mirror is not sufficient)
135
136=item git checkout and commit bit
fd838dcf
JV
137
138You will need a working C<git> installation, checkout of the perl
139git repository and perl commit bit. For information about working
c222ef46 140with perl and git, see F<pod/perlgit.pod>.
fd838dcf
JV
141
142If you are not yet a perl committer, you won't be able to make a
143release. Have a chat with whichever evil perl porter tried to talk
144you into the idea in the first place to figure out the best way to
145resolve the issue.
146
f6af4394 147
8c35d285 148=item Quotation for release announcement epigraph
f6af4394 149
b1288acc 150I<SKIP this step for RC>
f6af4394 151
6a958a95 152For all except an RC release of perl, you will need a quotation
b1288acc 153to use as an epigraph to your release announcement.
46743ef7 154
f6af4394
DM
155
156=back
157
b82efa27 158
2e831dfd 159=head2 Building a release - advance actions
8c35d285
JV
160
161The work of building a release candidate for a numbered release of
162perl generally starts several weeks before the first release candidate.
52a66c2c
DM
163Some of the following steps should be done regularly, but all I<must> be
164done in the run up to a release.
7277a900 165
7277a900 166
dc0a4df9 167=head3 dual-life CPAN module synchronisation
f6af4394 168
f6af4394
DM
169Ensure that dual-life CPAN modules are synchronised with CPAN. Basically,
170run the following:
171
db3f805e 172 $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
7277a900 173
f6af4394
DM
174to see any inconsistencies between the core and CPAN versions of distros,
175then fix the core, or cajole CPAN authors as appropriate. See also the
176C<-d> and C<-v> options for more detail. You'll probably want to use the
04dbb930
DG
177C<-c cachedir> option to avoid repeated CPAN downloads and may want to
178use C<-m file:///mirror/path> if you made a local CPAN mirror.
7277a900 179
f6af4394 180To see which core distro versions differ from the current CPAN versions:
7277a900 181
db3f805e 182 $ ./perl -Ilib Porting/core-cpan-diff -x -a
7277a900 183
6a958a95 184If you are making a MAINT release, run C<core-cpan-diff> on both blead and
636a1918
DM
185maint, then diff the two outputs. Compare this with what you expect, and if
186necessary, fix things up. For example, you might think that both blead
187and maint are synchronised with a particular CPAN module, but one might
188have some extra changes.
189
dc0a4df9
DM
190
191=head3 dual-life CPAN module stability
7277a900 192
f6af4394 193Ensure dual-life CPAN modules are stable, which comes down to:
7277a900
GS
194
195 for each module that fails its regression tests on $current
f6af4394
DM
196 did it fail identically on $previous?
197 if yes, "SEP" (Somebody Else's Problem)
198 else work out why it failed (a bisect is useful for this)
7277a900
GS
199
200 attempt to group failure causes
201
202 for each failure cause
f6af4394
DM
203 is that a regression?
204 if yes, figure out how to fix it
205 (more code? revert the code that broke it)
206 else
207 (presumably) it's relying on something un-or-under-documented
208 should the existing behaviour stay?
209 yes - goto "regression"
210 no - note it in perldelta as a significant bugfix
211 (also, try to inform the module's author)
1aff5354 212
dc0a4df9
DM
213
214=head3 smoking
7277a900 215
5157df7a
AB
216Similarly, monitor the smoking of core tests, and try to fix. See
217L<http://doc.procura.nl/smoke/index.html> for a summary. See also
218L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has
219the raw reports.
7277a900 220
636a1918
DM
221Similarly, monitor the smoking of perl for compiler warnings, and try to
222fix.
223
dc0a4df9
DM
224
225=head3 perldelta
636a1918 226
f6af4394 227Get perldelta in a mostly finished state.
db3f805e 228
04c2c53e 229Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that
636a1918
DM
230every section it lists is, if necessary, populated and complete. Copy
231edit the whole document.
f6af4394 232
f6af4394 233
dc0a4df9
DM
234=head3 Bump the version number
235
236Increase the version number (e.g. from 5.12.0 to 5.12.1).
04dbb930 237
6a958a95 238For a BLEAD-POINT release, this can happen on the day of the release. For a
04dbb930
DG
239release candidate for a stable perl, this should happen a week or two
240before the first release candidate to allow sufficient time for testing and
241smoking with the target version built into the perl executable. For
242subsequent release candidates and the final release, it it not necessary to
243bump the version further.
f6af4394 244
8b2227e6 245There is a tool to semi-automate this process:
f6af4394 246
8b2227e6 247 $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1
f6af4394 248
8b2227e6
LB
249Remember that this tool is largely just grepping for '5.10.0' or whatever,
250so it will generate false positives. Be careful not change text like
251"this was fixed in 5.10.0"!
ceb7f800 252
8b2227e6 253Use git status and git diff to select changes you want to keep.
ceb7f800 254
f6af4394
DM
255Be particularly careful with F<INSTALL>, which contains a mixture of
256C<5.10.0>-type strings, some of which need bumping on every release, and
e03f126c
Z
257some of which need to be left unchanged.
258The line in F<INSTALL> about "is binary incompatible with" requires a
259correct choice of earlier version to declare incompatibility with.
260
261Also note that this tool
52a66c2c
DM
262currently only detects a single substitution per line: so in particular,
263this line in README.vms needs special handling:
f6af4394
DM
264
265 rename perl-5^.10^.1.dir perl-5_10_1.dir
7277a900 266
6a958a95
DM
267When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the
268C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version
269you're releasing, unless you're
e43cb88f 270absolutely sure the release you're about to make is 100% binary compatible
6a958a95 271to an earlier release. When releasing a MAINT perl version, the C<PERL_API_*>
e43cb88f
TM
272constants C<MUST NOT> be changed as we aim to guarantee binary compatibility
273in maint branches.
45ce9531 274
17163f85
DM
275After editing, regenerate uconfig.h (this must be run on a system with a
276/bin/sh available):
22be9667 277
17163f85 278 $ perl regen/uconfig_h.pl
22be9667
JV
279
280Test your changes:
281
17163f85 282 $ git clean -xdf # careful if you don't have local files to keep!
22be9667
JV
283 $ ./Configure -des -Dusedevel
284 $ make
285 $ make test
286
54356a6f
JV
287Commit your changes:
288
289 $ git st
e91bd5c0
LB
290 $ git diff
291 B<review the delta carefully>
54356a6f
JV
292
293 $ git commit -a -m 'Bump the perl version in various places for 5.x.y'
dc0a62a1 294
21768cb3
FC
295At this point you may want to compare the commit with a previous bump to
296see if they look similar. See commit 8891dd8d for an example of a
297previous version bump.
298
dc0a4df9
DM
299When the version number is bumped, you should also update Module::CoreList
300(as described below in L<"update Module::CoreList">) to reflect the new
81fc59ef
DG
301version number.
302
dc0a4df9
DM
303
304=head3 update INSTALL
dc0a62a1
DM
305
306Review and update INSTALL to account for the change in version number;
307in particular, the "Coexistence with earlier versions of perl 5" section.
308
6a958a95
DM
309Be particularly careful with the section "Upgrading from 5.X.Y or earlier".
310The "X.Y" needs to be changed to the most recent version that we are
311I<not> binary compatible with.
312
313For MAINT and BLEAD-FINAL releases, this needs to refer to the last
314release in the previous development cycle (so for example, for a 5.14.x
315release, this would be 5.13.11).
316
317For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT
318release (so for 5.15.3 this would be 5.15.2).
319
dc0a4df9 320=head3 Check more build configurations
b82efa27 321
52a66c2c
DM
322Check some more build configurations. The check that setuid builds and
323installs is for < 5.11.0 only.
324
325 $ sh Configure -Dprefix=/tmp/perl-5.x.y -Uinstallusrbinperl \
326 -Duseshrplib -Dd_dosuid
327 $ make
328 $ LD_LIBRARY_PATH=`pwd` make test # or similar for useshrplib
7277a900 329
52a66c2c
DM
330 $ make suidperl
331 $ su -c 'make install'
332 $ ls -l .../bin/sperl
333 -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl
7277a900 334
52a66c2c 335(Then delete the installation directory.)
7277a900 336
52a66c2c 337XXX think of other configurations that need testing.
7277a900 338
dc0a4df9
DM
339
340=head3 update perlport
7277a900 341
347f5124
RGS
342L<perlport> has a section currently named I<Supported Platforms> that
343indicates which platforms are known to build in the current release.
344If necessary update the list and the indicated version number.
345
6a958a95
DM
346
347
2e831dfd
DM
348=head2 Building a release - on the day
349
b1288acc
DM
350This section describes the actions required to make a release
351that are performed on the actual day.
2e831dfd 352
2e831dfd 353
dc0a4df9 354=head3 re-check earlier actions
2e831dfd 355
dc0a4df9 356Review all the actions in the previous section,
2e831dfd
DM
357L<"Building a release - advance actions"> to ensure they are all done and
358up-to-date.
359
dc0a4df9
DM
360
361=head3 bump version number
8c35d285 362
6a958a95
DM
363For a BLEAD-POINT release, if you did not bump the perl version number as
364part of I<advance actions>, do that now.
04dbb930 365
dc0a4df9
DM
366
367=head3 finalize perldelta
04dbb930 368
04dbb930 369Finalize the perldelta. In particular, fill in the Acknowledgements
38195a8c
DG
370section. You can generate a list of contributors with checkAUTHORS.pl.
371For example:
372
c34fab5f 373 $ git log --pretty=fuller v5.13.${last}..HEAD | \
38195a8c 374 perl Porting/checkAUTHORS.pl --who -
04dbb930 375
ef86391b
AB
376Look at the previous L<perldelta> for how to write the opening
377paragraph of the Acknowledgements section. To get the amount of
378changed files and number of lines use this command:
379
c34fab5f 380 $ git diff --shortstat v5.13.${last}..HEAD | \
ef86391b
AB
381 ./perl -Ilib -nE 'my ($files, $insert, $delete) = /(\d+)/ga; say "$files files and ", $insert + $delete, " lines changed"'
382
383Making sure to round off the number of lines changed.
384
a0db33fe
DM
385Re-read the perldelta to try to find any embarrassing typos and thinkos;
386remove any C<TODO> or C<XXX> flags; update the "Known Problems" section
387with any serious issues for which fixes are not going to happen now; and
388run through pod and spell checkers, e.g.
2e831dfd 389
c5b87fed
FR
390 $ podchecker -warnings -warnings pod/perldelta.pod
391 $ spell pod/perldelta.pod
2e831dfd 392
a0db33fe
DM
393Also, you may want to generate and view an HTML version of it to check
394formatting, e.g.
2e831dfd 395
84c2dc44 396 $ ./perl -Ilib ext/Pod-Html/pod2html pod/perldelta.pod > /tmp/perldelta.html
2e831dfd 397
38195a8c
DG
398Another good HTML preview option is http://search.cpan.org/pod2html
399
400If you make changes, be sure to commit them.
401
dc0a4df9
DM
402
403=head3 build a clean perl
8c35d285 404
a0db33fe
DM
405Make sure you have a gitwise-clean perl directory (no modified files,
406unpushed commits etc):
8c35d285 407
a0db33fe 408 $ git status
24c5e187 409 $ git clean -dxf
8c35d285 410
dc0a4df9 411then configure and build perl so that you have a Makefile and porting tools:
8c35d285 412
52a66c2c 413 $ ./Configure -Dusedevel -des && make
8c35d285 414
dc0a4df9
DM
415
416=head3 update Module::CoreList
8c35d285 417
1bac61bb 418Update C<Module::CoreList> with module version data for the new release.
bfadf2ba 419
6a958a95 420Note that if this is a MAINT release, you should run the following actions
1bac61bb 421from the maint branch, but commit the C<CoreList.pm> changes in
a9d1f3db
LB
422I<blead> and subsequently cherry-pick any releases since the last
423maint release and then your recent commit. XXX need a better example
bfadf2ba 424
a0db33fe 425F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived
bfadf2ba 426modules on CPAN. It can use a full, local CPAN mirror or fall back
e8c01f92
SH
427to C<wget> or C<curl> to fetch only package metadata remotely. (If you're
428on Win32, then installing Cygwin is one way to have commands like C<wget>
429and C<curl> available.)
bfadf2ba
JV
430
431(If you'd prefer to have a full CPAN mirror, see
432http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN)
433
a0db33fe 434Then change to your perl checkout, and if necessary,
bfadf2ba 435
595f83ae 436 $ make
bfadf2ba 437
81fc59ef
DG
438If this not the first update for this version (e.g. if it was updated
439when the version number was originally bumped), first edit
d5bddf6e 440F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
2ce7d676
RGS
441entries for this version from the C<%released> and C<%version> hashes:
442they will have a key like C<5.010001> for 5.10.1.
52a66c2c
DM
443
444XXX the edit-in-place functionality of Porting/corelist.pl should
445be fixed to handle this automatically.
446
bf8ea215 447Then, If you have a local CPAN mirror, run:
bfadf2ba 448
bfadf2ba
JV
449 $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror
450
451Otherwise, run:
452
bfadf2ba
JV
453 $ ./perl -Ilib Porting/corelist.pl cpan
454
52a66c2c 455This will chug for a while, possibly reporting various warnings about
2a720090 456badly-indexed CPAN modules unrelated to the modules actually in core.
2ce7d676 457Assuming all goes well, it will update
d5bddf6e 458F<dist/Module-CoreList/lib/Module/CoreList.pm>.
bfadf2ba
JV
459
460Check that file over carefully:
461
d5bddf6e 462 $ git diff dist/Module-CoreList/lib/Module/CoreList.pm
bfadf2ba 463
bfadf2ba
JV
464If necessary, bump C<$VERSION> (there's no need to do this for
465every RC; in RC1, bump the version to a new clean number that will
466appear in the final release, and leave as-is for the later RCs and final).
467
468Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >>
469entry, as that is likely to reflect the previous version number.
470
cb9af4c0
AB
471Also edit Module::CoreList's new version number in its F<Changes>
472file.
e8c01f92 473
70855f8b
FC
474Add a perldelta entry for the new Module::CoreList version.
475
3dbfcde0
AB
476You should also add the version you're about to release to the
477L<Module::CoreList/CAVEATS> section which enumerates the perl releases
478that Module::CoreList covers.
479
a0db33fe 480In addition, if this is a final release (rather than a release candidate):
bfadf2ba
JV
481
482=over 4
483
484=item *
485
486Update this version's entry in the C<%released> hash with today's date.
487
488=item *
489
490Make sure that the script has correctly updated the C<CAVEATS> section
491
492=back
493
494Finally, commit the new version of Module::CoreList:
6a958a95 495(unless this is for MAINT; in which case commit it to blead first, then
a0db33fe 496cherry-pick it back).
bfadf2ba 497
770cf6ff 498 $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
bfadf2ba 499
dc0a4df9
DM
500
501=head3 check MANIFEST
bfadf2ba 502
a0db33fe 503Check that the manifest is sorted and correct:
8c35d285 504
a0db33fe 505 $ make distclean
300b5357 506 $ git clean -xdf # This shouldn't be necessary if distclean is correct
a0db33fe 507 $ perl Porting/manicheck
d5bddf6e 508
7081fd3a 509If manicheck turns up anything wrong, update MANIFEST and begin this step again.
a0db33fe 510
7081fd3a
JV
511 $ ./configure -des -Dusedevel
512 $ make test_porting
a0db33fe
DM
513 $ git commit -m 'Update MANIFEST' MANIFEST
514
dc0a4df9
DM
515
516=head3 update perlhist.pod
a0db33fe 517
e8a7a70e 518I<You MUST SKIP this step for a RC release>
a0db33fe 519
e8a7a70e
JV
520Add an entry to F<pod/perlhist.pod> with the release date, e.g.:
521
522 David 5.10.1 2009-Aug-06
a0db33fe
DM
523
524Make sure that the correct pumpking is listed in the left-hand column, and
525if this is the first release under the stewardship of a new pumpking, make
526sure that his or her name is listed in the section entitled
527C<THE KEEPERS OF THE PUMPKIN>.
528
529Be sure to commit your changes:
530
531 $ git commit -m 'add new release to perlhist' pod/perlhist.pod
8c35d285 532
dc0a4df9
DM
533
534=head3 update patchlevel.h
8c35d285 535
6a958a95 536I<You MUST SKIP this step for a BLEAD-POINT release>
d7eb1120 537
a42352ee
DM
538Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
539a final release, remove it. For example:
d7eb1120
DM
540
541 static const char * const local_patches[] = {
542 NULL
543 + ,"RC1"
544 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
545
546Be sure to commit your change:
547
548 $ git commit -m 'bump version to RCnnn' patchlevel.h
549
dc0a4df9
DM
550
551=head3 build, test and check a fresh perl
d7eb1120 552
a0db33fe
DM
553Build perl, then make sure it passes its own test suite, and installs:
554
555 $ git clean -xdf
a42352ee
DM
556 $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest
557
558 # or if it's an odd-numbered version:
a0db33fe 559 $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest
a42352ee 560
a0db33fe
DM
561 $ make test install
562
52a66c2c
DM
563Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and
564C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected,
a0db33fe 565especially as regards version numbers, patch and/or RC levels, and @INC
52a66c2c
DM
566paths. Note that as they have been been built from a git working
567directory, they will still identify themselves using git tags and
568commits.
569
570Then delete the temporary installation.
571
dc0a4df9
DM
572
573=head3 push the work so far
52a66c2c 574
a0db33fe
DM
575Push all your recent commits:
576
577 $ git push origin ....
578
96054f12 579
dc0a4df9 580=head3 tag the release
96054f12 581
e8c01f92 582Tag the release (e.g.):
96054f12 583
b6d23947 584 $ git tag v5.11.0 -m "First release of the v5.11 series!"
e8c01f92 585
6a958a95 586It is B<VERY> important that from this point forward, you not push
f662f3b7
JV
587your git changes to the Perl master repository. If anything goes
588wrong before you publish your newly-created tag, you can delete
589and recreate it. Once you push your tag, we're stuck with it
590and you'll need to use a new version number for your release.
591
dc0a4df9
DM
592
593=head3 build the tarball
a0db33fe 594
8c35d285
JV
595Create a tarball. Use the C<-s> option to specify a suitable suffix for
596the tarball and directory name:
597
598 $ cd root/of/perl/tree
599 $ make distclean
75a012fe
DM
600 $ git clean -xdf # make sure perl and git agree on files
601 $ git status # and there's nothing lying around
8c35d285 602
8c35d285
JV
603 $ perl Porting/makerel -b -s RC1 # for a release candidate
604 $ perl Porting/makerel -b # for a final release
605
606This creates the directory F<../perl-x.y.z-RC1> or similar, copies all
607the MANIFEST files into it, sets the correct permissions on them,
608adds DOS line endings to some, then tars it up as
609F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file.
610
6480287f
MT
611If you're getting your tarball suffixed with -uncommitted and you're sure
612your changes were all committed, you can override the suffix with:
613
614 $ perl Porting/makerel -b -s ''
96054f12 615
8c35d285
JV
616XXX if we go for extra tags and branches stuff, then add the extra details
617here
618
c8c95eea
NC
619Optionally, you might want to compress your tarball more. Unix F<gzip>
620doesn't actually produce the smallest possible DEFLATE output. If you have the
621AdvanceCOMP suite (e.g. the C<advancecomp> port on macports), you can run
622
623 $ advdef -z -4 ../perl-x.y.z-RC1.tar.gz
624
625which will probably shrink your tarball by about 5%. Over the lifetime of
626your distribution this will save a lot of people a small amount of download
627time and disk space, which adds up.
628
629(7-Zip on Windows is the same code as AdvanceCOMP, so Windows users get the
630smallest files first time)
631
8c35d285 632
dc0a4df9 633Finally, clean up the temporary directory, e.g.
a42352ee
DM
634
635 $ rm -rf ../perl-x.y.z-RC1
636
dc0a4df9
DM
637
638=head3 test the tarball
639
640=over 4
641
a42352ee
DM
642=item *
643
8c35d285
JV
644Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you
645have access to.
646
647=item *
648
649Download the tarball to some other machine. For a release candidate,
650you really want to test your tarball on two or more different platforms
651and architectures. The #p5p IRC channel on irc.perl.org is a good place
652to find willing victims.
653
654=item *
655
656Check that basic configuration and tests work on each test machine:
657
658 $ ./Configure -des && make all test
f6af4394
DM
659
660=item *
661
8c35d285
JV
662Check that the test harness and install work on each test machine:
663
a42352ee 664 $ make distclean
8c35d285 665 $ ./Configure -des -Dprefix=/install/path && make all test_harness install
a42352ee 666 $ cd /install/path
8c35d285
JV
667
668=item *
669
670Check that the output of C<perl -v> and C<perl -V> are as expected,
671especially as regards version numbers, patch and/or RC levels, and @INC
672paths.
673
674Note that the results may be different without a F<.git/> directory,
675which is why you should test from the tarball.
676
677=item *
678
459fc3ca
DM
679Run the Installation Verification Procedure utility:
680
9651cacc 681 $ ./perl utils/perlivp
459fc3ca
DM
682 ...
683 All tests successful.
684 $
685
686=item *
687
d60a1044
DM
688Compare the pathnames of all installed files with those of the previous
689release (i.e. against the last installed tarball on this branch which you
690have previously verified using this same procedure). In particular, look
691for files in the wrong place, or files no longer included which should be.
692For example, suppose the about-to-be-released version is 5.10.1 and the
693previous is 5.10.0:
694
695 cd installdir-5.10.0/
696 find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1
697 cd installdir-5.10.1/
698 find . -type f | sort > /tmp/f2
699 diff -u /tmp/f[12]
700
701=item *
702
8c35d285
JV
703Bootstrap the CPAN client on the clean install:
704
16c60e4e 705 $ bin/perl -MCPAN -e "shell"
8c35d285 706
16c60e4e
AB
707If you're running this on Win32 you probably also need a set of Unix
708command-line tools available for CPAN to function correctly without
e8c01f92
SH
709Perl alternatives like LWP installed. Cygwin is an obvious choice.)
710
8c35d285
JV
711=item *
712
a42352ee
DM
713Try installing a popular CPAN module that's reasonably complex and that
714has dependencies; for example:
8c35d285 715
a42352ee
DM
716 CPAN> install Inline
717 CPAN> quit
8c35d285
JV
718
719Check that your perl can run this:
720
16c60e4e 721 $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f"
a42352ee
DM
722 42
723 $
8c35d285
JV
724
725=item *
726
727Bootstrap the CPANPLUS client on the clean install:
728
75a012fe 729 $ bin/cpanp
8c35d285 730
e8c01f92
SH
731(Again, on Win32 you'll need something like Cygwin installed, but make sure
732that you don't end up with its various F<bin/cpan*> programs being found on
733the PATH before those of the Perl that you're trying to test.)
734
8c35d285
JV
735=item *
736
a42352ee 737Install an XS module, for example:
8c35d285 738
a42352ee
DM
739 CPAN Terminal> i DBI
740 CPAN Terminal> quit
741 $ bin/perl -MDBI -e 1
75a012fe 742 $
8c35d285
JV
743
744=item *
745
7f89f796 746Check that the L<perlbug> utility works. Try the following:
47b1f096 747
a14438df 748 $ bin/perlbug
47b1f096
DM
749 ...
750 Subject: test bug report
751 Local perl administrator [yourself]:
752 Editor [vi]:
753 Module:
754 Category [core]:
755 Severity [low]:
756 (edit report)
757 Action (Send/Display/Edit/Subject/Save to File): f
758 Name of file to save message in [perlbug.rep]:
759 Action (Send/Display/Edit/Subject/Save to File): q
760
761and carefully examine the output (in F<perlbug.rep]>), especially
762the "Locally applied patches" section. If everything appears okay, then
75a012fe
DM
763delete the file, and try it again, this time actually submitting the bug
764report. Check that it shows up, then remember to close it!
47b1f096 765
dc0a4df9
DM
766=back
767
768
769=head3 monitor smokes
47b1f096 770
f6af4394
DM
771Wait for the smoke tests to catch up with the commit which this release is
772based on (or at least the last commit of any consequence).
7277a900 773
f6af4394
DM
774Then check that the smoke tests pass (particularly on Win32). If not, go
775back and fix things.
7277a900 776
6a958a95 777Note that for I<BLEAD-POINT> releases this may not be practical. It takes a
1eefd7d5 778long time for the smokers to catch up, especially the Win32
6a958a95
DM
779smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL>
780releases, but for I<BLEAD-POINT> releases sometimes the best you can do is
781to plead with people on IRC to test stuff on their platforms, fire away,
782and then hope for the best.
7277a900 783
dc0a4df9
DM
784
785=head3 upload to PAUSE
7277a900 786
f6af4394 787Once smoking is okay, upload it to PAUSE. This is the point of no return.
db3f805e
JV
788If anything goes wrong after this point, you will need to re-prepare
789a new release with a new minor version or RC number.
790
a14438df
DM
791 https://pause.perl.org/
792
793(Login, then select 'Upload a file to CPAN')
794
45924287
RS
795If your workstation is not connected to a high-bandwidth,
796high-reliability connection to the Internet, you should probably use the
797"GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the
798new release from wherever you put it for testers to find it. This will
799eliminate anxious gnashing of teeth while you wait to see if your
80015 megabyte HTTP upload successfully completes across your slow, twitchy
c27b4e97
SH
801cable modem. You can make use of your home directory on dromedary for
802this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to
803F</home/USERNAME/public_html>, where F<USERNAME> is your login account
804on dromedary. I<Remember>: if your upload is partially successful, you
805may need to contact a PAUSE administrator or even bump the version of perl.
45924287 806
a42352ee 807Upload both the .gz and .bz2 versions of the tarball.
f6af4394 808
c27b4e97 809Wait until you receive notification emails from the PAUSE indexer
38195a8c 810confirming that your uploads have been received. IMPORTANT -- you will
b28f69c2
Z
811probably get an email that indexing has failed, due to module permissions.
812This is considered normal.
38195a8c
DG
813
814Do not proceed any further until you are sure that your tarballs are on
815CPAN. Check your authors directory on one of the "fast" CPAN mirrors
b28f69c2 816(e.g., cpan.hexten.net
38195a8c 817or cpan.cpantesters.org) to confirm that your uploads have been successful.
c27b4e97 818
dc0a4df9
DM
819
820=head3 publish tag
210de33e 821
f662f3b7 822Now that you've shipped the new perl release to PAUSE, it's
e8c01f92 823time to publish the tag you created earlier to the public git repo (e.g.):
f662f3b7
JV
824
825 $ git push origin tag v5.11.0
f6af4394 826
dc0a4df9
DM
827
828=head3 disarm patchlevel.h
f6af4394 829
6a958a95 830I<You MUST SKIP this step for BLEAD-POINT release>
113f3f4c 831
a42352ee 832Disarm the F<patchlevel.h> change; for example,
d7eb1120
DM
833
834 static const char * const local_patches[] = {
835 NULL
836 - ,"RC1"
837 PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */
838
839Be sure to commit your change:
840
841 $ git commit -m 'disarm RCnnn bump' patchlevel.h
a14438df 842 $ git push origin ....
d7eb1120 843
2e831dfd 844
dc0a4df9
DM
845
846=head3 announce to p5p
2e831dfd 847
db3f805e 848Mail p5p to announce your new release, with a quote you prepared earlier.
f6af4394 849
dc0a4df9
DM
850
851=head3 update epigraphs.pod
f6af4394 852
85531b0a
DG
853Add your quote to F<Porting/epigraphs.pod> and commit it.
854
dc0a4df9
DM
855
856=head3 Module::CoreList nagging
85531b0a 857
bc4c40f2 858I<You MUST SKIP this step for RC>
8c35d285 859
75a012fe
DM
860Remind the current maintainer of C<Module::CoreList> to push a new release
861to CPAN.
7277a900 862
dc0a4df9
DM
863
864=head3 new perldelta
a2cba4bc 865
bc4c40f2 866I<You MUST SKIP this step for RC>
7277a900 867
c5b87fed 868Create a new perldelta.
7277a900 869
17163f85
DM
870B<Note>: currently, the buildtoc below must be run in a I<built> perl source
871directory, as at least one of the pod files it expects to find is
872autogenerated: perluniprops.pod. But you can't build perl if you've added
873the new perldelta file and not updated toc. So, make sure you have a built
dc0a4df9 874perl (with a pod/perluniprops.pod file) now, I<before> continuing.
17163f85
DM
875
876First, update the F<pod/.gitignore> file to ignore the next
877release's generated F<pod/perlNNNdelta.pod> file rather than this release's
5ef3945b
SH
878one which we are about to set in stone (where NNN is the perl version number
879without the dots. i.e. 5135 for 5.13.5).
880
17163f85
DM
881 $ (edit pod/.gitignore )
882 $ git add pod/.gitignore
8e967a1c 883
17163f85
DM
884Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>,
885and edit the moved delta file to change the C<NAME> from C<perldelta> to
886C<perlNNNdelta>. For example, assuming you just released 5.10.1, and are
887about to create the 5.10.2 perldelta:
8e967a1c 888
17163f85 889 $ rm pod/perl5101delta.pod # remove the auto-generated file, if any
c5b87fed
FR
890 $ git mv pod/perldelta.pod pod/perl5101delta.pod
891 $ (edit pod/perl5101delta.pod to retitle)
8e967a1c 892 $ git add pod/perl5101delta.pod
c5b87fed 893
17163f85
DM
894Then create a new empty perldelta.pod file for the new release; see
895F<Porting/how_to_write_a_perldelta.pod>. You should be able to do this by
896just copying in a skeleton template and then doing a quick fix up of the
897version numbers. Then commit the move and the new file.
898
c5b87fed
FR
899 $ cp -i Porting/perldelta_template.pod pod/perldelta.pod
900 $ (edit pod/perldelta.pod)
901 $ git add pod/perldelta.pod
902 $ git commit -m 'create perldelta for 5.10.2'
8e967a1c 903
dc0a4df9 904=head3 update perldelta TOC and references
17163f85
DM
905
906Now you need to update various tables of contents related to perldelta,
907most of which can be generated automatically.
7277a900 908
8a51675c
FC
909Edit F<pod.lst>: add the new entry for the perlNNNdelta file for the
910current version (the file that will be symlinked to perldelta).
7277a900 911
17163f85
DM
912Manually create a temporary link to the new delta file; normally this is
913done from the Makefile, but the Makefile is updated by buildtoc, and
914buildtoc won't run without the file there:
915
916 $ ln -s perldelta.pod pod/perl5102delta.pod
917
75a012fe
DM
918Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
919the following files:
57433fbf
JV
920
921 MANIFEST
75a012fe 922 Makefile.SH
57433fbf 923 pod/perl.pod
57433fbf 924 vms/descrip_mms.template
75a012fe
DM
925 win32/Makefile
926 win32/makefile.mk
927 win32/pod.mak
928
75a012fe
DM
929Finally, commit:
930
c5b87fed 931 $ git commit -a -m 'update TOC for perlNNNdelta'
75a012fe 932
21768cb3
FC
933At this point you may want to compare the commit with a previous bump to
934see if they look similar. See commit dd885b5 for an example of a
75a012fe 935previous version bump.
57433fbf 936
dc0a4df9
DM
937
938=head3 bump version
57433fbf 939
6a958a95 940I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
dc0a62a1 941
6a958a95
DM
942If this was a BLEAD-FINAL release (i.e. the first release of a new maint
943series, 5.x.0 where x is even), then bump the version in the blead branch
944in git, e.g. 5.12.0 to 5.13.0.
17163f85
DM
945
946First, add a new feature bundle to F<lib/feature.pm>, initially by just
947copying the exiting entry, and bump the file's $VERSION; e.g.
948
949 "5.14" => [qw(switch say state unicode_strings)],
950 + "5.15" => [qw(switch say state unicode_strings)],
addebd58 951
dc0a4df9
DM
952Then follow the section L<"Bump the version number"> to bump the version
953in the remaining files and test and commit.
17163f85 954
17163f85 955
dc0a4df9
DM
956=head3 push commits
957
958Finally, push any commits done above.
959
960 $ git push origin ....
961
962
963=head3 create maint branch
17163f85 964
6a958a95 965I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>
17163f85 966
6a958a95
DM
967If this was a BLEAD-FINAL release (i.e. the first release of a new maint
968series, 5.x.0 where x is even), then create a new maint branch based on
969the commit tagged as the current release.
7277a900 970
233ca920
JV
971Assuming you're using git 1.7.x or newer:
972
17163f85 973 $ git checkout -b maint-5.12 v5.12.0
233ca920 974 $ git push origin -u maint-5.12
addebd58 975
dc0a4df9 976
d5722260
DK
977=head3 make the maint branch available in the APC
978
979Clone the new branch into /srv/gitcommon/branches on camel so the APC will
980receive its changes.
981
07697565 982 $ git clone --branch maint-5.14 /gitroot/perl.git \
d5722260 983 ? /srv/gitcommon/branches/perl-5.14.x
07697565 984 $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x
d5722260
DK
985
986And nag the sysadmins to make this directory available via rsync.
987
988
dc0a4df9 989=head3 copy perldelta.pod to other branches
addebd58 990
6a958a95 991I<You MUST SKIP this step for RC, BLEAD-POINT>
8c35d285 992
c5b87fed 993Copy the perldelta.pod for this release into the other branches; for
75a012fe 994example:
7277a900 995
c5b87fed 996 $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
75a012fe
DM
997 $ git add pod/perl5101delta.pod
998
999Edit F<pod.lst> to add an entry for the file, e.g.:
1000
1001 perl5101delta Perl changes in version 5.10.1
bc4c40f2 1002
75a012fe 1003Then rebuild various files:
7277a900 1004
75a012fe
DM
1005 $ perl pod/buildtoc --build-all
1006
1007Finally, commit:
1008
1009 $ git commit -a -m 'add perlXXXdelta'
7277a900 1010
dc0a4df9
DM
1011
1012=head3 update perlhist.pod in other branches
7277a900 1013
f6af4394 1014Make sure any recent F<pod/perlhist.pod> entries are copied to
e8a7a70e 1015F<perlhist.pod> on other branches
f6af4394 1016e.g.
7277a900 1017
f6af4394 1018 5.8.9 2008-Dec-14
7277a900 1019
dc0a4df9
DM
1020
1021=head3 bump RT version number
6e40fbf9 1022
1530afd8
LB
1023Log into http://rt.perl.org/ and check whether the new version is
1024in the RT fields C<Perl Version> and C<Fixed In>. If not, send an
1025email to C<perlbug-admin at perl.org> requesting this.
dc0a4df9
DM
1026
1027=head3 Relax!
a3738a12 1028
bc4c40f2
JV
1029I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some
1030much-needed rest and relaxation>.
8c35d285
JV
1031
1032Thanks for releasing perl!
1033
7277a900 1034
b28f69c2
Z
1035=head2 Building a release - the day after
1036
dc0a4df9
DM
1037=head3 check tarball availability
1038
1039Check various website entries to make sure the that tarball has appeared
1040and is properly indexed:
1041
b28f69c2
Z
1042=over 4
1043
1044=item *
1045
98df743a
Z
1046Check your author directory under L<http://www.cpan.org/authors/id/>
1047to ensure that the tarballs are available on the website.
b28f69c2
Z
1048
1049=item *
1050
98df743a
Z
1051Check C</src> on CPAN (on a fast mirror) to ensure that links to
1052the new tarballs have appeared. There should be links in C</src/5.0>
1053(which is accumulating all new versions), links in C</src> (which shows
1054only the latest version on each branch), and an appropriate mention in
1055C</src/README.html> (which describes the latest versions).
1056
1057These links should appear automatically, some hours after upload.
1058If they don't, or the C<README.html> description is inadequate,
1059ask Ask <ask@perl.org>.
b28f69c2
Z
1060
1061=item *
1062
98df743a
Z
1063Check L<http://www.cpan.org/src/> to ensure that the C</src> updates
1064have been correctly mirrored to the website.
1065If they haven't, ask Ask <ask@perl.org>.
1066
1067=item *
b28f69c2 1068
98df743a
Z
1069Check L<http://search.cpan.org> to see if it has indexed the distribution.
1070It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>.
b28f69c2 1071
dc0a4df9 1072=back
b28f69c2 1073
dc0a4df9
DM
1074
1075=head3 update dev.perl.org
1076
1077I<This step ONLY for BLEAD-POINT and MAINT>
98df743a 1078
e294df83 1079Ask Leo Lapworth to update L<http://dev.perl.org/perl5/>.
b28f69c2 1080
b28f69c2 1081
7277a900
GS
1082=head1 SOURCE
1083
f6af4394
DM
1084Based on
1085http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html,
1086plus a whole bunch of other sources, including private correspondence.
7277a900
GS
1087
1088=cut
1089