Commit | Line | Data |
---|---|---|
7277a900 GS |
1 | =head1 NAME |
2 | ||
3 | release_managers_guide - Releasing a new version of perl 5.x | |
4 | ||
636a1918 DM |
5 | XXX as of Jul 2009, this file is still a work-in-progress. I think it |
6 | contains all the actions needed to build a release, but things may have | |
7 | got skipped, and some things could do with polishing. Note that things | |
8 | change each release, there may be new things not covered here, or | |
9 | tools may need updating. DAPM | |
f6af4394 | 10 | |
7277a900 GS |
11 | =head1 SYNOPSIS |
12 | ||
f6af4394 DM |
13 | This document describes the series of tasks required - some automatic, some |
14 | manual - to produce a perl release of some description, be that a snaphot, | |
8c35d285 | 15 | release candidate, or final, numbered release of maint or blead. |
f6af4394 | 16 | |
8c35d285 JV |
17 | The release process has traditionally been executed by the current |
18 | pumpking. | |
7277a900 | 19 | |
8c35d285 JV |
20 | This document both helps as a check-list for the release engineer |
21 | and is a base for ideas on how the various tasks could be automated | |
22 | or distributed. | |
7277a900 | 23 | |
636a1918 | 24 | The outline of a typical release cycle is as follows: |
f6af4394 | 25 | |
636a1918 | 26 | (5.10.1 is released, and post-release actions have been done) |
f6af4394 DM |
27 | |
28 | ...time passes... | |
29 | ||
30 | an occasional snapshot is released, that still identifies itself as | |
31 | 5.10.1 | |
32 | ||
33 | ...time passes... | |
34 | ||
35 | a few weeks before the release, a number of steps are performed, | |
36 | including bumping the version to 5.10.2 | |
636a1918 DM |
37 | |
38 | ...a few weeks passes... | |
46743ef7 | 39 | |
f6af4394 DM |
40 | perl-5.10.2-RC1 is released |
41 | ||
42 | perl-5.10.2 is released | |
43 | ||
44 | post-release actions are performed, including creating new | |
45 | perl5103delta.pod | |
46 | ||
47 | ... the cycle continues ... | |
7277a900 GS |
48 | |
49 | =head1 DETAILS | |
50 | ||
8c35d285 JV |
51 | Some of the tasks described below apply to all four types of |
52 | release of Perl. (snapshot, RC, final release of maint, final | |
53 | release of blead). Some of these tasks apply only to a subset | |
54 | of these release types. If a step does not apply to a given | |
55 | type of release, you will see a notation to that effect at | |
56 | the beginning of the step. | |
57 | ||
58 | =head2 Release types | |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item Snapshot | |
63 | ||
64 | A snapshot is intended to encourage in-depth testing from time-to-time, | |
65 | for example after a key point in the stabilisation of a branch. It | |
66 | requires fewer steps than a full release, and the version number of perl in | |
67 | the tarball will usually be the same as that of the previous release. | |
68 | ||
69 | =item Release Candidate (RC) | |
70 | ||
71 | XXX Describe me | |
72 | ||
73 | =item Stable/Maint release | |
74 | ||
75 | At this point you should have a working release candidate with few or no | |
76 | changes since. | |
77 | ||
78 | It's essentially the same procedure as for making a release candidate, but | |
79 | with a whole bunch of extra post-release steps. | |
80 | ||
81 | =item Blead release | |
82 | ||
83 | It's essentially the same procedure as for making a release candidate, but | |
84 | with a whole bunch of extra post-release steps. | |
85 | ||
86 | =back | |
7277a900 | 87 | |
fd838dcf JV |
88 | =head2 Prerequisites |
89 | ||
90 | Before you can make an official release of perl, there are a few | |
91 | hoops you need to jump through: | |
92 | ||
93 | =over 4 | |
94 | ||
8c35d285 JV |
95 | =item PAUSE account |
96 | ||
97 | I<SKIP this step for SNAPSHOT> | |
fd838dcf JV |
98 | |
99 | Make sure you have a PAUSE account suitable for uploading a perl release. | |
100 | If you don't have a PAUSE account, then request one: | |
101 | ||
102 | https://pause.perl.org/pause/query?ACTION=request_id | |
103 | ||
104 | Check that your account is allowed to upload perl distros: goto | |
105 | https://pause.perl.org/, login, then select 'upload file to CPAN'; there | |
106 | should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas | |
107 | König to add your ID to the list of people allowed to upload something | |
108 | called perl. You can find Andreas' email address at: | |
4d2c8158 | 109 | |
fd838dcf JV |
110 | https://pause.perl.org/pause/query?ACTION=pause_04imprint |
111 | ||
8c35d285 JV |
112 | =item CPAN mirror |
113 | ||
114 | Some release engineering steps require a full mirror of the CPAN. | |
115 | Work to fall back to using a remote mirror via HTTP is incomplete | |
116 | but ongoing. (No, a minicpan mirror is not sufficient) | |
117 | ||
118 | =item git checkout and commit bit | |
fd838dcf JV |
119 | |
120 | You will need a working C<git> installation, checkout of the perl | |
121 | git repository and perl commit bit. For information about working | |
122 | with perl and git, see F<pod/perlrepository.pod>. | |
123 | ||
124 | If you are not yet a perl committer, you won't be able to make a | |
125 | release. Have a chat with whichever evil perl porter tried to talk | |
126 | you into the idea in the first place to figure out the best way to | |
127 | resolve the issue. | |
128 | ||
f6af4394 | 129 | |
8c35d285 | 130 | =item Quotation for release announcement epigraph |
f6af4394 | 131 | |
8c35d285 | 132 | I<SKIP this step for SNAPSHOT and RC> |
f6af4394 | 133 | |
8c35d285 JV |
134 | For a numbered blead or maint release of perl, you will need a quotation |
135 | to use as an epigraph to your release announcement. (There's no harm | |
136 | in having one for a snapshot, but it's not required). | |
46743ef7 | 137 | |
f6af4394 DM |
138 | |
139 | =back | |
140 | ||
f6af4394 | 141 | |
2e831dfd | 142 | =head2 Building a release - advance actions |
8c35d285 JV |
143 | |
144 | The work of building a release candidate for a numbered release of | |
145 | perl generally starts several weeks before the first release candidate. | |
146 | Some of these should be done regularly, but all I<must> be done in the | |
147 | runup to a release. | |
7277a900 GS |
148 | |
149 | =over 4 | |
150 | ||
f6af4394 DM |
151 | =item * |
152 | ||
8c35d285 JV |
153 | I<You MAY SKIP this step for SNAPSHOT> |
154 | ||
f6af4394 DM |
155 | Ensure that dual-life CPAN modules are synchronised with CPAN. Basically, |
156 | run the following: | |
157 | ||
db3f805e | 158 | $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs |
7277a900 | 159 | |
f6af4394 DM |
160 | to see any inconsistencies between the core and CPAN versions of distros, |
161 | then fix the core, or cajole CPAN authors as appropriate. See also the | |
162 | C<-d> and C<-v> options for more detail. You'll probably want to use the | |
163 | C<-c cachedir> option to avoid repeated CPAN downloads. | |
7277a900 | 164 | |
f6af4394 | 165 | To see which core distro versions differ from the current CPAN versions: |
7277a900 | 166 | |
db3f805e | 167 | $ ./perl -Ilib Porting/core-cpan-diff -x -a |
7277a900 | 168 | |
636a1918 DM |
169 | if you are making a maint release, run C<core-cpan-diff> on both blead and |
170 | maint, then diff the two outputs. Compare this with what you expect, and if | |
171 | necessary, fix things up. For example, you might think that both blead | |
172 | and maint are synchronised with a particular CPAN module, but one might | |
173 | have some extra changes. | |
174 | ||
f6af4394 | 175 | =item * |
7277a900 | 176 | |
8c35d285 JV |
177 | I<You MAY SKIP this step for SNAPSHOT> |
178 | ||
f6af4394 | 179 | Ensure dual-life CPAN modules are stable, which comes down to: |
7277a900 GS |
180 | |
181 | for each module that fails its regression tests on $current | |
f6af4394 DM |
182 | did it fail identically on $previous? |
183 | if yes, "SEP" (Somebody Else's Problem) | |
184 | else work out why it failed (a bisect is useful for this) | |
7277a900 GS |
185 | |
186 | attempt to group failure causes | |
187 | ||
188 | for each failure cause | |
f6af4394 DM |
189 | is that a regression? |
190 | if yes, figure out how to fix it | |
191 | (more code? revert the code that broke it) | |
192 | else | |
193 | (presumably) it's relying on something un-or-under-documented | |
194 | should the existing behaviour stay? | |
195 | yes - goto "regression" | |
196 | no - note it in perldelta as a significant bugfix | |
197 | (also, try to inform the module's author) | |
1aff5354 | 198 | |
f6af4394 | 199 | =item * |
7277a900 | 200 | |
8c35d285 JV |
201 | I<You MAY SKIP this step for SNAPSHOT> |
202 | ||
f6af4394 | 203 | Similarly, monitor the smoking of core tests, and try to fix. |
7277a900 | 204 | |
f6af4394 | 205 | =item * |
7277a900 | 206 | |
8c35d285 JV |
207 | I<You MAY SKIP this step for SNAPSHOT> |
208 | ||
636a1918 DM |
209 | Similarly, monitor the smoking of perl for compiler warnings, and try to |
210 | fix. | |
211 | ||
212 | =item * | |
213 | ||
8c35d285 JV |
214 | I<You MAY SKIP this step for SNAPSHOT> |
215 | ||
f6af4394 DM |
216 | Run F<Porting/cmpVERSION.pl> to compare the current source tree with the |
217 | previous version to check for for modules that have identical version | |
218 | numbers but different contents, e.g.: | |
7277a900 | 219 | |
f6af4394 DM |
220 | $ cd ~/some-perl-root |
221 | $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 . | |
222 | ||
223 | then bump the version numbers of any non-dual-life modules that have | |
224 | changed since the previous release, but which still have the old version | |
225 | number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x), | |
226 | then compare against both. | |
227 | ||
228 | Note that some of the files listed may be generated (e.g. copied from ext/ | |
229 | to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm); | |
230 | make sure you edit the correct file! | |
231 | ||
232 | Once all version numbers have been bumped, re-run the checks. | |
233 | ||
234 | Then run again without the -x option, to check that dual-life modules are | |
235 | also sensible. | |
236 | ||
55878aed JV |
237 | =item * |
238 | ||
8c35d285 JV |
239 | I<You MAY SKIP this step for SNAPSHOT> |
240 | ||
f6af4394 | 241 | Get perldelta in a mostly finished state. |
db3f805e | 242 | |
636a1918 DM |
243 | Peruse F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that |
244 | every section it lists is, if necessary, populated and complete. Copy | |
245 | edit the whole document. | |
f6af4394 DM |
246 | |
247 | =item * | |
248 | ||
8c35d285 JV |
249 | I<You MUST SKIP this step for SNAPSHOT> |
250 | ||
2e831dfd DM |
251 | A week or two before the first release candidate, bump the perl version |
252 | number (e.g. from 5.10.0 to 5.10.1), to allow sufficient time for testing | |
253 | and smoking with the target version built into the perl executable. For | |
254 | subsequent release candidates and the final release, it it not necessary | |
255 | to bump the version further. | |
f6af4394 DM |
256 | |
257 | There is a tool to semi-automate this process. It works in two stages. | |
258 | First, it generates a list of suggested changes, which you review and | |
259 | edit; then you feed this list back and it applies the edits. So, first | |
260 | scan the source dir looking for likely candidates: | |
261 | ||
262 | $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan | |
263 | ||
264 | This produces a file containing a list of suggested edits, eg: | |
265 | ||
266 | NetWare/Makefile | |
267 | ||
268 | 89: -MODULE_DESC = "Perl 5.10.0 for NetWare" | |
269 | +MODULE_DESC = "Perl 5.10.1 for NetWare" | |
270 | ||
271 | i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown. | |
272 | Review the file carefully, and delete any -/+ line pairs that you don't | |
273 | want changing. Remember that this tool is largely just grepping for '5.10.0' | |
274 | or whatever, so it will generate false positives. Be careful not change | |
275 | text like "this was fixed in 5.10.0"! Then run: | |
276 | ||
277 | $ Porting/bump-perl-version -u < /tmp/scan | |
278 | ||
279 | which will update all the files shown; then commit the changes. | |
280 | ||
281 | Be particularly careful with F<INSTALL>, which contains a mixture of | |
282 | C<5.10.0>-type strings, some of which need bumping on every release, and | |
283 | some of which need to be left. Also note that this tool currently only | |
284 | performs a single change per line, so in particular, this line in | |
285 | README.vms needs special handling: | |
286 | ||
287 | rename perl-5^.10^.1.dir perl-5_10_1.dir | |
7277a900 | 288 | |
dc0a62a1 DM |
289 | |
290 | =item * | |
291 | ||
8c35d285 JV |
292 | I<You MUST SKIP this step for SNAPSHOT> |
293 | ||
dc0a62a1 DM |
294 | Review and update INSTALL to account for the change in version number; |
295 | in particular, the "Coexistence with earlier versions of perl 5" section. | |
296 | ||
f6af4394 | 297 | =item * |
7277a900 | 298 | |
8c35d285 JV |
299 | I<You MUST SKIP this step for SNAPSHOT> |
300 | ||
f6af4394 DM |
301 | Update the F<Changes> file to contain the git log command which would show |
302 | all the changes in this release. You will need assume the existence of a | |
303 | not-yet created tag for the forthcoming release; e.g. | |
7277a900 | 304 | |
f6af4394 | 305 | git log ... perl-5.10.0..perl5.12.0 |
7277a900 | 306 | |
f6af4394 DM |
307 | Due to warts in the perforce-to-git migration, some branches require extra |
308 | exclusions to avoid other branches being pulled in. Make sure you have the | |
309 | correct incantation: replace the not-yet-created tag with C<HEAD> and see | |
310 | if git log produces roughly the right number of commits across roughly the | |
311 | right time period. | |
7277a900 | 312 | |
dc0a62a1 | 313 | |
f6af4394 | 314 | =item * |
7277a900 | 315 | |
f6af4394 | 316 | Check some more build configurations, e.g. |
7277a900 | 317 | |
f6af4394 DM |
318 | -Duseshrplib -Dd_dosuid |
319 | make suidperl | |
7277a900 | 320 | |
f6af4394 DM |
321 | Check that setuid installs works (for < 5.11.0 only). |
322 | XXX any other configs? | |
7277a900 | 323 | |
7277a900 | 324 | |
f6af4394 | 325 | =item * |
7277a900 | 326 | |
8c35d285 JV |
327 | I<You MAY SKIP this step for SNAPSHOT> |
328 | ||
f6af4394 | 329 | Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if |
ce80ee91 JV |
330 | necessary, update the script to include new alias mappings for porters |
331 | already in F<AUTHORS> | |
f6af4394 | 332 | |
ce80ee91 | 333 | $ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS - |
f6af4394 | 334 | |
8c35d285 | 335 | =item * |
f6af4394 | 336 | |
8c35d285 | 337 | I<You MAY SKIP this step for SNAPSHOT> |
f6af4394 | 338 | |
8c35d285 JV |
339 | As there are no regular smokes [ XXX yet - please fix?] find out about the |
340 | state of the current branch on VMS. If the branch you're releasing on | |
341 | is failing tests on VMS, you may not want to do a release. | |
342 | ||
2e831dfd DM |
343 | =back |
344 | ||
345 | =head2 Building a release - on the day | |
346 | ||
347 | This section describes the actions required to make a release (or snapshot | |
348 | etc) that are performed on the actual day. | |
349 | ||
350 | =over 4 | |
351 | ||
352 | =item * | |
353 | ||
354 | Review all the items in the previous section, | |
355 | L<"Building a release - advance actions"> to ensure they are all done and | |
356 | up-to-date. | |
357 | ||
8c35d285 JV |
358 | =item * |
359 | ||
a0db33fe | 360 | I<You MAY SKIP this step for SNAPSHOT> |
2e831dfd | 361 | |
a0db33fe DM |
362 | Re-read the perldelta to try to find any embarrassing typos and thinkos; |
363 | remove any C<TODO> or C<XXX> flags; update the "Known Problems" section | |
364 | with any serious issues for which fixes are not going to happen now; and | |
365 | run through pod and spell checkers, e.g. | |
2e831dfd | 366 | |
bf8ea215 JV |
367 | $ podchecker -warnings -warnings pod/perl5101delta.pod |
368 | $ spell pod/perl5101delta.pod | |
2e831dfd | 369 | |
a0db33fe DM |
370 | Also, you may want to generate and view an HTML version of it to check |
371 | formatting, e.g. | |
2e831dfd | 372 | |
bf8ea215 | 373 | $ perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html |
2e831dfd | 374 | |
8c35d285 JV |
375 | =item * |
376 | ||
a0db33fe DM |
377 | Make sure you have a gitwise-clean perl directory (no modified files, |
378 | unpushed commits etc): | |
8c35d285 | 379 | |
a0db33fe | 380 | $ git status |
8c35d285 JV |
381 | |
382 | =item * | |
383 | ||
a0db33fe DM |
384 | If not already built, Configure and build perl so that you have a Makefile |
385 | and porting tools: | |
8c35d285 | 386 | |
a0db33fe DM |
387 | $ ./Configure -Dusedevel -des |
388 | $ make | |
8c35d285 JV |
389 | |
390 | =item * | |
391 | ||
a0db33fe DM |
392 | Check that files managed by F<regen.pl> and friends are up to date. From |
393 | within your working directory: | |
8c35d285 | 394 | |
a0db33fe DM |
395 | $ git status |
396 | $ make regen | |
397 | $ make regen_perly | |
398 | $ git status | |
8c35d285 | 399 | |
a0db33fe DM |
400 | If any of the files managed by F<regen.pl> have changed, then you should |
401 | re-make perl to check that it's okay, then commit the updated versions: | |
8c35d285 | 402 | |
a0db33fe | 403 | $ git commit -a -m 'make regn; make regn_perly' |
8c35d285 JV |
404 | |
405 | =item * | |
406 | ||
a0db33fe | 407 | Rebuild META.yml: |
bfadf2ba | 408 | |
a0db33fe DM |
409 | $ rm META.yml |
410 | $ make META.yml | |
411 | $ git diff | |
bfadf2ba | 412 | |
a0db33fe DM |
413 | XXX it would be nice to make Porting/makemeta use regen_lib.pl |
414 | to get the same 'update the file if its changed' functionality | |
415 | we get with 'make regen' etc. | |
bfadf2ba | 416 | |
a0db33fe | 417 | Commit META.yml if it has changed: |
dd0e54ba | 418 | |
a0db33fe | 419 | $ git commit -m 'Update META.yml' META.yml |
dd0e54ba | 420 | |
bfadf2ba JV |
421 | =item * |
422 | ||
423 | I<You MUST SKIP this step for SNAPSHOT> | |
424 | ||
bfadf2ba JV |
425 | Update C<Module::Corelist>. |
426 | ||
427 | Note that if this is a maint release, you should run the following actions | |
dd0e54ba DM |
428 | from the maint directory, but commit the C<Corelist.pm> changes in |
429 | I<blead> and subsequently cherry-pick it. | |
bfadf2ba | 430 | |
a0db33fe | 431 | F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived |
bfadf2ba JV |
432 | modules on CPAN. It can use a full, local CPAN mirror or fall back |
433 | to C<wget> or C<curl> to fetch only package metadata remotely. | |
434 | ||
435 | (If you'd prefer to have a full CPAN mirror, see | |
436 | http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN) | |
437 | ||
a0db33fe | 438 | Then change to your perl checkout, and if necessary, |
bfadf2ba | 439 | |
a0db33fe | 440 | $ make perl |
bfadf2ba | 441 | |
bf8ea215 | 442 | Then, If you have a local CPAN mirror, run: |
bfadf2ba | 443 | |
bfadf2ba JV |
444 | $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror |
445 | ||
446 | Otherwise, run: | |
447 | ||
bfadf2ba JV |
448 | $ ./perl -Ilib Porting/corelist.pl cpan |
449 | ||
450 | This will chug for a while. Assuming all goes well, it will | |
a0db33fe | 451 | update F<lib/Module/CoreList.pm>. |
bfadf2ba JV |
452 | |
453 | Check that file over carefully: | |
454 | ||
455 | $ git diff lib/Module/CoreList.pm | |
456 | ||
a0db33fe DM |
457 | In particular, if this not the first update for this version, make sure |
458 | that there isn't a duplicated entry (e.g. '5.010001' entries for both RC1 | |
459 | and RC2). | |
460 | ||
461 | XXX the edit-in-place functionality of Porting/corelist.pl should | |
462 | be fixed to allow for this | |
bfadf2ba JV |
463 | |
464 | If necessary, bump C<$VERSION> (there's no need to do this for | |
465 | every RC; in RC1, bump the version to a new clean number that will | |
466 | appear in the final release, and leave as-is for the later RCs and final). | |
467 | ||
468 | Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> | |
469 | entry, as that is likely to reflect the previous version number. | |
470 | ||
a0db33fe | 471 | In addition, if this is a final release (rather than a release candidate): |
bfadf2ba JV |
472 | |
473 | =over 4 | |
474 | ||
475 | =item * | |
476 | ||
477 | Update this version's entry in the C<%released> hash with today's date. | |
478 | ||
479 | =item * | |
480 | ||
481 | Make sure that the script has correctly updated the C<CAVEATS> section | |
482 | ||
483 | =back | |
484 | ||
485 | Finally, commit the new version of Module::CoreList: | |
a0db33fe DM |
486 | (unless this is for maint; in which case commit it blead first, then |
487 | cherry-pick it back). | |
bfadf2ba JV |
488 | |
489 | $ git commit -m 'Updated Module::CoreList for the 5.x.y release' \ | |
a0db33fe DM |
490 | lib/Module/CoreList.pm |
491 | ||
bfadf2ba | 492 | |
bfadf2ba JV |
493 | =item * |
494 | ||
a0db33fe | 495 | Check that the manifest is sorted and correct: |
8c35d285 | 496 | |
a0db33fe DM |
497 | $ make manisort |
498 | $ make distclean | |
499 | $ perl Porting/manicheck | |
500 | ||
501 | Commit MANIFEST if it has changed: | |
502 | ||
503 | $ git commit -m 'Update MANIFEST' MANIFEST | |
504 | ||
505 | =item * | |
506 | ||
507 | I<You MUST SKIP this step for SNAPSHOT> | |
508 | ||
509 | Add an entry to F<pod/perlhist.pod> with the current date, e.g.: | |
510 | ||
511 | David 5.10.1-RC1 2009-Aug-06 | |
512 | ||
513 | Make sure that the correct pumpking is listed in the left-hand column, and | |
514 | if this is the first release under the stewardship of a new pumpking, make | |
515 | sure that his or her name is listed in the section entitled | |
516 | C<THE KEEPERS OF THE PUMPKIN>. | |
517 | ||
518 | Be sure to commit your changes: | |
519 | ||
520 | $ git commit -m 'add new release to perlhist' pod/perlhist.pod | |
8c35d285 JV |
521 | |
522 | =item * | |
523 | ||
d7eb1120 DM |
524 | I<You MUST SKIP this step for SNAPSHOT> |
525 | ||
a42352ee DM |
526 | Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is |
527 | a final release, remove it. For example: | |
d7eb1120 DM |
528 | |
529 | static const char * const local_patches[] = { | |
530 | NULL | |
531 | + ,"RC1" | |
532 | PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ | |
533 | ||
534 | Be sure to commit your change: | |
535 | ||
536 | $ git commit -m 'bump version to RCnnn' patchlevel.h | |
537 | ||
538 | =item * | |
539 | ||
a0db33fe DM |
540 | Build perl, then make sure it passes its own test suite, and installs: |
541 | ||
542 | $ git clean -xdf | |
a42352ee DM |
543 | $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest |
544 | ||
545 | # or if it's an odd-numbered version: | |
a0db33fe | 546 | $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest |
a42352ee | 547 | |
a0db33fe DM |
548 | $ make test install |
549 | ||
550 | =item * | |
551 | ||
552 | Check that the output of C<perl -v> and C<perl -V> are as expected, | |
553 | especially as regards version numbers, patch and/or RC levels, and @INC | |
554 | paths. | |
555 | ||
556 | =item * | |
557 | ||
558 | Push all your recent commits: | |
559 | ||
560 | $ git push origin .... | |
561 | ||
562 | ||
563 | =item * | |
564 | ||
8c35d285 JV |
565 | Create a tarball. Use the C<-s> option to specify a suitable suffix for |
566 | the tarball and directory name: | |
567 | ||
568 | $ cd root/of/perl/tree | |
569 | $ make distclean | |
570 | $ git clean -xdf # make sure perl and git agree on files | |
571 | ||
572 | $ perl Porting/makerel -b -s `git describe` # for a snapshot | |
573 | $ perl Porting/makerel -b -s RC1 # for a release candidate | |
574 | $ perl Porting/makerel -b # for a final release | |
575 | ||
576 | This creates the directory F<../perl-x.y.z-RC1> or similar, copies all | |
577 | the MANIFEST files into it, sets the correct permissions on them, | |
578 | adds DOS line endings to some, then tars it up as | |
579 | F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file. | |
580 | ||
581 | XXX if we go for extra tags and branches stuff, then add the extra details | |
582 | here | |
583 | ||
584 | =item * | |
585 | ||
a42352ee DM |
586 | Clean up the temporary directory, e.g. |
587 | ||
588 | $ rm -rf ../perl-x.y.z-RC1 | |
589 | ||
590 | =item * | |
591 | ||
8c35d285 JV |
592 | Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you |
593 | have access to. | |
594 | ||
595 | =item * | |
596 | ||
597 | Download the tarball to some other machine. For a release candidate, | |
598 | you really want to test your tarball on two or more different platforms | |
599 | and architectures. The #p5p IRC channel on irc.perl.org is a good place | |
600 | to find willing victims. | |
601 | ||
602 | =item * | |
603 | ||
604 | Check that basic configuration and tests work on each test machine: | |
605 | ||
606 | $ ./Configure -des && make all test | |
f6af4394 DM |
607 | |
608 | =item * | |
609 | ||
8c35d285 JV |
610 | Check that the test harness and install work on each test machine: |
611 | ||
a42352ee | 612 | $ make distclean |
8c35d285 | 613 | $ ./Configure -des -Dprefix=/install/path && make all test_harness install |
a42352ee | 614 | $ cd /install/path |
8c35d285 JV |
615 | |
616 | =item * | |
617 | ||
618 | Check that the output of C<perl -v> and C<perl -V> are as expected, | |
619 | especially as regards version numbers, patch and/or RC levels, and @INC | |
620 | paths. | |
621 | ||
622 | Note that the results may be different without a F<.git/> directory, | |
623 | which is why you should test from the tarball. | |
624 | ||
625 | =item * | |
626 | ||
627 | Bootstrap the CPAN client on the clean install: | |
628 | ||
629 | $ ./bin/perl -MCPAN -e'shell' | |
630 | ||
631 | =item * | |
632 | ||
a42352ee DM |
633 | Try installing a popular CPAN module that's reasonably complex and that |
634 | has dependencies; for example: | |
8c35d285 | 635 | |
a42352ee DM |
636 | CPAN> install Inline |
637 | CPAN> quit | |
8c35d285 JV |
638 | |
639 | Check that your perl can run this: | |
640 | ||
a42352ee DM |
641 | $ ./bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f' |
642 | 42 | |
643 | $ | |
8c35d285 JV |
644 | |
645 | =item * | |
646 | ||
647 | Bootstrap the CPANPLUS client on the clean install: | |
648 | ||
649 | $ ./bin/cpanp | |
650 | ||
8c35d285 JV |
651 | =item * |
652 | ||
a42352ee | 653 | Install an XS module, for example: |
8c35d285 | 654 | |
a42352ee DM |
655 | CPAN Terminal> i DBI |
656 | CPAN Terminal> quit | |
657 | $ bin/perl -MDBI -e 1 | |
8c35d285 JV |
658 | |
659 | ||
660 | =item * | |
661 | ||
8c35d285 JV |
662 | I<You MAY SKIP this step for SNAPSHOT> |
663 | ||
f6af4394 DM |
664 | Wait for the smoke tests to catch up with the commit which this release is |
665 | based on (or at least the last commit of any consequence). | |
7277a900 | 666 | |
f6af4394 DM |
667 | Then check that the smoke tests pass (particularly on Win32). If not, go |
668 | back and fix things. | |
7277a900 | 669 | |
7277a900 | 670 | |
f6af4394 | 671 | =item * |
7277a900 | 672 | |
8c35d285 JV |
673 | I<You MUST SKIP this step for SNAPSHOT> |
674 | ||
f6af4394 | 675 | Once smoking is okay, upload it to PAUSE. This is the point of no return. |
db3f805e JV |
676 | If anything goes wrong after this point, you will need to re-prepare |
677 | a new release with a new minor version or RC number. | |
678 | ||
a42352ee | 679 | Upload both the .gz and .bz2 versions of the tarball. |
f6af4394 | 680 | |
210de33e DM |
681 | =item * |
682 | ||
8c35d285 JV |
683 | I<You MUST SKIP this step for SNAPSHOT> |
684 | ||
2e831dfd DM |
685 | Create a tag for the exact git revision you built the release from. |
686 | C<commit> below is the commit corresponding to the tarball. It can be | |
687 | omitted if there have been no further commits since the tarball was | |
688 | created. | |
210de33e | 689 | |
2e831dfd | 690 | $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' <commit> |
210de33e | 691 | $ git push origin tag perl-5.10.1-RC1 |
f6af4394 DM |
692 | |
693 | =item * | |
694 | ||
2e831dfd DM |
695 | I<You MUST SKIP this step for SNAPSHOT> |
696 | ||
a42352ee | 697 | Disarm the F<patchlevel.h> change; for example, |
d7eb1120 DM |
698 | |
699 | static const char * const local_patches[] = { | |
700 | NULL | |
701 | - ,"RC1" | |
702 | PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ | |
703 | ||
704 | Be sure to commit your change: | |
705 | ||
706 | $ git commit -m 'disarm RCnnn bump' patchlevel.h | |
707 | ||
2e831dfd DM |
708 | |
709 | =item * | |
710 | ||
db3f805e | 711 | Mail p5p to announce your new release, with a quote you prepared earlier. |
f6af4394 DM |
712 | |
713 | =item * | |
714 | ||
8c35d285 JV |
715 | I<You MAY SKIP this step for SNAPSHOT> |
716 | ||
f6af4394 | 717 | Wait 24 hours or so, then post the announcement to use.perl.org. |
addebd58 DM |
718 | (if you don't have access rights to post news, ask someone like Rafael to |
719 | do it for you.) | |
f6af4394 | 720 | |
f6af4394 | 721 | =item * |
7277a900 | 722 | |
8c35d285 | 723 | I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> |
7277a900 | 724 | |
f6af4394 DM |
725 | Ask Jarkko to update http://www.cpan.org/src/README.html and |
726 | Rafael to update http://dev.perl.org/perl5/ | |
7277a900 | 727 | |
f6af4394 | 728 | =item * |
7277a900 | 729 | |
8c35d285 JV |
730 | I<You MUST SKIP this step for SNAPSHOT, RC> |
731 | ||
f6af4394 DM |
732 | Create a new empty perlNNNdelta.pod file for the current release + 1; |
733 | see F<Porting/how_to_write_a_perldelta.pod>. | |
734 | [ XXX Perhaps we should have an empty template file we can copy in. ] | |
7277a900 | 735 | |
a2cba4bc | 736 | In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous |
57433fbf | 737 | entry as 'D', |
a2cba4bc | 738 | |
57433fbf | 739 | Change perlNNNdelta references to the new version in these files |
7277a900 | 740 | |
f6af4394 DM |
741 | INSTALL |
742 | win32/Makefile.mk | |
743 | win32/Makefile | |
744 | Makefile.SH | |
745 | README | |
7277a900 | 746 | |
f6af4394 DM |
747 | Also, edit the previous delta file to change the C<NAME> from C<perldelta> |
748 | to C<perlNNNdelta>. | |
7277a900 | 749 | |
f6af4394 DM |
750 | These two lists of files probably aren't exhaustive; do a recursive grep |
751 | on the previous filename to look for suitable candidates. | |
7277a900 | 752 | |
f6af4394 | 753 | (see 16410843ea for an example). |
7277a900 | 754 | |
f6af4394 | 755 | =item * |
7277a900 | 756 | |
57433fbf JV |
757 | Run C<perl pod/buildtoc --build-all> to update the following files: |
758 | ||
759 | MANIFEST | |
760 | pod/perl.pod | |
761 | win32/pod.mak | |
762 | vms/descrip_mms.template | |
763 | ||
764 | If you modified perldelta.pod, (F<vms/descrip_mms.template> will | |
765 | needs a manual edit to bump the C<perldelta.pod> entry - it would | |
766 | be good for someone to figure out the fix.) | |
767 | ||
768 | =item * | |
769 | ||
8c35d285 | 770 | I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> |
dc0a62a1 | 771 | |
8c35d285 JV |
772 | If this was a maint release, then edit F<Porting/mergelog> to change |
773 | all the C<d> (deferred) flags to C<.> (needs review). | |
addebd58 | 774 | |
addebd58 DM |
775 | =item * |
776 | ||
8c35d285 | 777 | I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> |
addebd58 | 778 | |
8c35d285 JV |
779 | If this was a major release (5.x.0), then create a new maint branch |
780 | based on the commit tagged as the current release and bump the version | |
781 | in the blead branch in git, e.g. 5.12.0 to 5.13.0. | |
addebd58 DM |
782 | |
783 | [ XXX probably lots more stuff to do, including perldelta, | |
f6af4394 | 784 | C<lib/feature.pm> ] |
7277a900 | 785 | |
8c35d285 | 786 | XXX need a git recipe |
addebd58 DM |
787 | |
788 | =item * | |
789 | ||
8c35d285 JV |
790 | I<You MUST SKIP this step for SNAPSHOT, RC, BLEAD> |
791 | ||
f6af4394 DM |
792 | Copy the perlNNNdelta.pod for this release into the other branches, and |
793 | remember to update these files on those branches too: | |
7277a900 | 794 | |
f6af4394 DM |
795 | MANIFEST |
796 | pod.lst | |
797 | pod/perl.pod | |
798 | vms/descrip_mms.template | |
799 | win32/pod.mak | |
7277a900 | 800 | |
f6af4394 | 801 | (see fc5be80860 for an example). |
7277a900 | 802 | |
f6af4394 | 803 | =item * |
7277a900 | 804 | |
8c35d285 JV |
805 | I<You MUST SKIP this step for SNAPSHOT> |
806 | ||
f6af4394 DM |
807 | Make sure any recent F<pod/perlhist.pod> entries are copied to |
808 | F<perlhist.pod> on other branches; typically the RC* and final entries, | |
809 | e.g. | |
7277a900 | 810 | |
f6af4394 DM |
811 | 5.8.9-RC1 2008-Nov-10 |
812 | 5.8.9-RC2 2008-Dec-06 | |
813 | 5.8.9 2008-Dec-14 | |
7277a900 | 814 | |
6e40fbf9 DM |
815 | =item * |
816 | ||
8c35d285 JV |
817 | I<You MUST SKIP this step for SNAPSHOT, RC> |
818 | ||
6e40fbf9 DM |
819 | Remind the current maintainer of C<Module::CoreList> to push a new release |
820 | to CPAN. | |
821 | ||
8c35d285 JV |
822 | =item * |
823 | ||
824 | I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some much-needed | |
825 | rest and relaxation>. | |
826 | ||
827 | Thanks for releasing perl! | |
828 | ||
7277a900 GS |
829 | =back |
830 | ||
831 | =head1 SOURCE | |
832 | ||
f6af4394 DM |
833 | Based on |
834 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html, | |
835 | plus a whole bunch of other sources, including private correspondence. | |
7277a900 GS |
836 | |
837 | =cut | |
838 |