Commit | Line | Data |
7277a900 |
1 | |
2 | =head1 NAME |
3 | |
4 | release_managers_guide - Releasing a new version of perl 5.x |
5 | |
f6af4394 |
6 | XXX as of Jul 2009, this file is still a work-in-progress - DAPM |
7 | |
7277a900 |
8 | =head1 SYNOPSIS |
9 | |
f6af4394 |
10 | This document describes the series of tasks required - some automatic, some |
11 | manual - to produce a perl release of some description, be that a snaphot, |
12 | release candidate, or final release. |
13 | |
7277a900 |
14 | The release process is primarily executed by the current pumpking. |
15 | |
1aff5354 |
16 | This document both helps as a check-list for the pumpking and is |
7277a900 |
17 | a base for ideas on how the various tasks could be automated or |
18 | distributed. |
19 | |
f6af4394 |
20 | The outline of a release cycle is as follows: |
21 | |
22 | (5.10.1 is released, and post-release action have been done) |
23 | |
24 | ...time passes... |
25 | |
26 | an occasional snapshot is released, that still identifies itself as |
27 | 5.10.1 |
28 | |
29 | ...time passes... |
30 | |
31 | a few weeks before the release, a number of steps are performed, |
32 | including bumping the version to 5.10.2 |
33 | |
34 | perl-5.10.2-RC1 is released |
35 | |
36 | perl-5.10.2 is released |
37 | |
38 | post-release actions are performed, including creating new |
39 | perl5103delta.pod |
40 | |
41 | ... the cycle continues ... |
7277a900 |
42 | |
43 | =head1 DETAILS |
44 | |
7277a900 |
45 | |
f6af4394 |
46 | =head2 Building a snapshot |
47 | |
48 | A snapshot is intended to encourage in-depth testing from time-to-time, |
49 | for example after a key point in the stabilisation of a branch. It |
50 | requires less steps than a full release, and the version number of perl in |
51 | the tarball will usually still be the old one. |
52 | |
53 | =over 4 |
54 | |
55 | =item * |
56 | |
57 | As there are no regular smokes [ XXX yet - please fix?] find out about the |
58 | state of VMS. If it's bad, think again. |
59 | |
60 | =item * |
61 | |
62 | Rebuild META.yml: |
63 | |
64 | $ rm META.yml |
65 | $ make META.yml |
66 | |
67 | and commit it if it's changed. |
68 | |
69 | =item * |
70 | |
71 | Check that the manifest is sorted and correct: |
72 | |
73 | $ make distclean |
74 | $ perl Porting/manisort |
75 | $ perl Porting/manicheck |
76 | |
77 | =item * |
78 | |
79 | If this is a release candidate or final release, add an entry to |
80 | F<pod/perlhist.pod> with the current date, e.g. |
81 | |
82 | 5.8.9-RC1 2008-Nov-10 |
83 | |
ce4f4fe2 |
84 | Make sure the correct pumpking is listed, and if this is your first time, |
f6af4394 |
85 | append your name to C<THE KEEPERS OF THE PUMPKIN>. |
86 | |
87 | =item * |
88 | |
89 | Build perl, then make sure it passes its own test suite, and installs. |
90 | |
91 | =item * |
92 | |
93 | Create a tarball. Use the C<-s> option to specify a suitable suffix for |
94 | the tarball and directory name: |
95 | |
96 | $ cd root/of/perl/tree |
97 | $ git clean -xdf # make sure perl and git agree on files |
98 | |
99 | $ perl Porting/makerel -s `git describe` # for a snapshot |
100 | $ perl Porting/makerel -s RC1 # for a release candidate |
101 | $ perl Porting/makerel # for a final release |
102 | |
103 | This creates the directory F<../perl-x.y.z-RC1> or similar, copies all |
104 | the MANIFEST files into it, sets the correct permissions on them, |
105 | adds DOS line endings to some, then tars it up as |
106 | F<../perl-x.y.z-RC1.tar.gz>. |
107 | |
108 | XXX if we go for extra tags and branches stuff, then add the extra details |
109 | here |
110 | |
111 | =item * |
112 | |
113 | Copy the tarball to a web server somewhere you have access to. |
114 | |
115 | =item * |
116 | |
117 | Download the tarball to some other machine (for a release candidate, to two or |
118 | more servers: IRC is good for this). |
119 | |
120 | =item * |
121 | |
122 | Check that C<./Configure -des && make all test> works in one place. |
123 | |
124 | =item * |
125 | |
126 | Check that C<./Configure ... && make all test_harness install> works. |
127 | |
128 | =item * |
129 | |
130 | Check that the output of C<perl -v> and C<perl -V> are as expected, |
131 | especially as regards version numbers, patch and/or RC levels, and @INC |
132 | paths. Note that the results may be different without a F<.git/> directory, |
133 | which is why you should test from the tarball. |
134 | |
135 | =item * |
136 | |
137 | Bootstrap the CPAN client on the clean install. |
138 | |
139 | =item * |
140 | |
141 | Install CPANPLUS. |
142 | XXX pick something new; this is now bundled |
143 | |
144 | =item * |
145 | |
146 | Bootstrap the CPANPLUS client. |
147 | |
148 | =item * |
149 | |
150 | Install an XS module. |
151 | |
152 | =item * |
153 | |
154 | If all is well, announce the snaphot to p5p. (For a release candidate, |
155 | instead follow the further steps described later.) |
156 | |
157 | =back |
158 | |
159 | =head2 Actions prior to the first release candidate |
160 | |
161 | A week or two before the first release candidate, there are some additional |
162 | tasks you should perform (actually, some of these should be done regularly |
163 | anyway, but they definitely need doing now): |
7277a900 |
164 | |
165 | =over 4 |
166 | |
f6af4394 |
167 | =item * |
168 | |
169 | Check F<Maintainers.pl> for consistency; both these commands should |
170 | produce no output: |
171 | |
172 | perl Porting/Maintainers --checkmani |
173 | perl Porting/Maintainers --checkmani lib/ ext/ |
174 | |
175 | =item * |
176 | |
177 | Ensure that dual-life CPAN modules are synchronised with CPAN. Basically, |
178 | run the following: |
179 | |
180 | ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs |
7277a900 |
181 | |
f6af4394 |
182 | to see any inconsistencies between the core and CPAN versions of distros, |
183 | then fix the core, or cajole CPAN authors as appropriate. See also the |
184 | C<-d> and C<-v> options for more detail. You'll probably want to use the |
185 | C<-c cachedir> option to avoid repeated CPAN downloads. |
7277a900 |
186 | |
f6af4394 |
187 | To see which core distro versions differ from the current CPAN versions: |
7277a900 |
188 | |
f6af4394 |
189 | ./perl -Ilib Porting/core-cpan-diff -x -a |
7277a900 |
190 | |
f6af4394 |
191 | =item * |
7277a900 |
192 | |
f6af4394 |
193 | Ensure dual-life CPAN modules are stable, which comes down to: |
7277a900 |
194 | |
195 | for each module that fails its regression tests on $current |
f6af4394 |
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 |
199 | |
200 | attempt to group failure causes |
201 | |
202 | for each failure cause |
f6af4394 |
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 | |
f6af4394 |
213 | =item * |
7277a900 |
214 | |
f6af4394 |
215 | Similarly, monitor the smoking of core tests, and try to fix. |
7277a900 |
216 | |
f6af4394 |
217 | =item * |
7277a900 |
218 | |
f6af4394 |
219 | Run F<Porting/cmpVERSION.pl> to compare the current source tree with the |
220 | previous version to check for for modules that have identical version |
221 | numbers but different contents, e.g.: |
7277a900 |
222 | |
f6af4394 |
223 | $ cd ~/some-perl-root |
224 | $ ./perl -Ilib Porting/cmpVERSION.pl -xd ~/my_perl-tarballs/perl-5.10.0 . |
225 | |
226 | then bump the version numbers of any non-dual-life modules that have |
227 | changed since the previous release, but which still have the old version |
228 | number. If there is more than one maintenance branch (e.g. 5.8.x, 5.10.x), |
229 | then compare against both. |
230 | |
231 | Note that some of the files listed may be generated (e.g. copied from ext/ |
232 | to lib/, or a script like lib/lib_pm.PL is run to produce lib/lib.pm); |
233 | make sure you edit the correct file! |
234 | |
235 | Once all version numbers have been bumped, re-run the checks. |
236 | |
237 | Then run again without the -x option, to check that dual-life modules are |
238 | also sensible. |
239 | |
240 | |
241 | =item * |
242 | |
243 | Get perldelta in a mostly finished state. |
244 | XXX expand |
245 | |
246 | =item * |
247 | |
248 | Bump the perl version number (e.g. from 5.10.0 to 5.10.1). |
249 | |
250 | There is a tool to semi-automate this process. It works in two stages. |
251 | First, it generates a list of suggested changes, which you review and |
252 | edit; then you feed this list back and it applies the edits. So, first |
253 | scan the source dir looking for likely candidates: |
254 | |
255 | $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan |
256 | |
257 | This produces a file containing a list of suggested edits, eg: |
258 | |
259 | NetWare/Makefile |
260 | |
261 | 89: -MODULE_DESC = "Perl 5.10.0 for NetWare" |
262 | +MODULE_DESC = "Perl 5.10.1 for NetWare" |
263 | |
264 | i.e. in the file F<NetWare/Makefile>, line 89 would be changed as shown. |
265 | Review the file carefully, and delete any -/+ line pairs that you don't |
266 | want changing. Remember that this tool is largely just grepping for '5.10.0' |
267 | or whatever, so it will generate false positives. Be careful not change |
268 | text like "this was fixed in 5.10.0"! Then run: |
269 | |
270 | $ Porting/bump-perl-version -u < /tmp/scan |
271 | |
272 | which will update all the files shown; then commit the changes. |
273 | |
274 | Be particularly careful with F<INSTALL>, which contains a mixture of |
275 | C<5.10.0>-type strings, some of which need bumping on every release, and |
276 | some of which need to be left. Also note that this tool currently only |
277 | performs a single change per line, so in particular, this line in |
278 | README.vms needs special handling: |
279 | |
280 | rename perl-5^.10^.1.dir perl-5_10_1.dir |
7277a900 |
281 | |
dc0a62a1 |
282 | |
283 | =item * |
284 | |
285 | Review and update INSTALL to account for the change in version number; |
286 | in particular, the "Coexistence with earlier versions of perl 5" section. |
287 | |
f6af4394 |
288 | =item * |
7277a900 |
289 | |
f6af4394 |
290 | Update the F<Changes> file to contain the git log command which would show |
291 | all the changes in this release. You will need assume the existence of a |
292 | not-yet created tag for the forthcoming release; e.g. |
7277a900 |
293 | |
f6af4394 |
294 | git log ... perl-5.10.0..perl5.12.0 |
7277a900 |
295 | |
f6af4394 |
296 | Due to warts in the perforce-to-git migration, some branches require extra |
297 | exclusions to avoid other branches being pulled in. Make sure you have the |
298 | correct incantation: replace the not-yet-created tag with C<HEAD> and see |
299 | if git log produces roughly the right number of commits across roughly the |
300 | right time period. |
7277a900 |
301 | |
dc0a62a1 |
302 | |
f6af4394 |
303 | =item * |
7277a900 |
304 | |
f6af4394 |
305 | Check some more build configurations, e.g. |
7277a900 |
306 | |
f6af4394 |
307 | -Duseshrplib -Dd_dosuid |
308 | make suidperl |
7277a900 |
309 | |
f6af4394 |
310 | Check that setuid installs works (for < 5.11.0 only). |
311 | XXX any other configs? |
7277a900 |
312 | |
f6af4394 |
313 | =item * |
7277a900 |
314 | |
f6af4394 |
315 | Make sure you have a PAUSE account suitable for uploading a perl release. |
316 | If you don't have a PAUSE account, then request one: |
7277a900 |
317 | |
f6af4394 |
318 | https://pause.perl.org/pause/query?ACTION=request_id |
7277a900 |
319 | |
f6af4394 |
320 | Check that your account is allowed to upload perl distros: goto |
321 | https://pause.perl.org/, login, then select 'upload file to CPAN'; there |
322 | should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas |
323 | to add your ID to the list of people allowed to upload something called |
324 | perl. |
7277a900 |
325 | |
f6af4394 |
326 | =item * |
7277a900 |
327 | |
f6af4394 |
328 | Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if |
329 | necessary, update the script to include new alias mappings. |
7277a900 |
330 | |
f6af4394 |
331 | XXX This script is currently broken (7/2009). It needs updating to work |
332 | with git and a lack of Changes files. |
333 | |
334 | =back |
335 | |
336 | =head2 Building a release candidate |
337 | |
338 | (At this point you should already have performed the actions described in |
dc0a62a1 |
339 | L</"Actions prior to the first release candidate">.) You should review |
340 | that section to ensure that everything there has done, and to see whether |
341 | any of those actions (such as consistency checks) need to be repeated. |
f6af4394 |
342 | |
343 | =over 4 |
344 | |
345 | =item * |
346 | |
347 | Re-read the perldelta to try to find any embarrassing typos and thinkos; |
348 | remove any C<TODO> or C<XXX> flags; and run through pod and spell |
349 | checkers. [XXX show how] |
350 | |
351 | =item * |
352 | |
353 | Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a |
354 | final release, remove it. [ XXX how now?? see 34813 for old way ] |
355 | |
356 | =item * |
357 | |
358 | Update C<Module::Corelist>. |
210de33e |
359 | |
ce4f4fe2 |
360 | Note that if this is a maint release, you should run the following actions |
210de33e |
361 | from the maint directory, but edit the C<Corelist.pm> in I<blead> and |
362 | subsequently cherry-pick it. |
363 | |
364 | First, in order to update the C<%upstream> and C<%bug_tracker> hashes, |
365 | the C<Porting/corelist.pl> script requires you to have a local CPAN |
366 | mirror. See http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN for |
367 | more details, but basically: |
368 | |
369 | $ mkdir ~/cpan-mirror |
370 | $ rsync -av --delete ftp.funet.fi::CPAN ~/cpan-mirror/ |
371 | |
372 | (and re-run the rsync each time you need it to be up-to-date). |
373 | [XXX this really needs fixing to not require a whole CPAN mirror] |
374 | |
375 | If necessary, bump C<$VERSION> (there's no need to do this for |
376 | every RC; in RC1, bump the version to a new clean number that will |
377 | appear in the final release, and leave as-is for the later RCs and final). |
378 | |
379 | Then do |
380 | |
381 | $ cd ~/perl/root; make perl |
382 | $ ./perl -Ilib Porting/corelist.pl ~/cpan-mirror/ > /tmp/corelist |
383 | |
384 | This creates a file that looks something like |
385 | |
386 | 5.010001 => { |
387 | 'AnyDBM_File' => '1.00', |
388 | ... |
389 | }, |
390 | |
391 | %upstream = ( |
392 | 'App::Prove' => undef, |
393 | ... |
394 | ); |
395 | |
396 | %bug_tracker = ( |
397 | 'App::Prove' => 'http://rt.cpan.org/...', |
398 | ... |
399 | ); |
400 | |
210de33e |
401 | Cut and paste these tables into F<lib/Module/CoreList.pm>: the module |
402 | version list should be appended as the last entry in the C<%version> hash |
403 | (or replaced, if we've already added it for an earlier release candidate), |
404 | while the existing C<%upstream> and C<%bug_tracker> hashes should be |
405 | replaced with the new versions. |
406 | |
ce4f4fe2 |
407 | Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> |
210de33e |
408 | entry, as that is likely to reflect the previous version number. |
409 | |
410 | Then, add the current perl version to the C<CAVEATS> paragraph. |
411 | |
412 | Add or update an entry to the C<%released> hash, including today's date |
413 | (if this is just a release candidate, set the date to '????-??-??'). |
414 | |
7277a900 |
415 | |
f6af4394 |
416 | =item * |
417 | |
418 | Follow the instructions in the section L</"Building a snapshot">, then |
419 | carry on with the extra steps that follow here. |
420 | |
421 | =item * |
7277a900 |
422 | |
addebd58 |
423 | Disarm the patchlevel.h change [ XXX expand ] |
424 | |
425 | =item * |
426 | |
f6af4394 |
427 | Wait for the smoke tests to catch up with the commit which this release is |
428 | based on (or at least the last commit of any consequence). |
7277a900 |
429 | |
f6af4394 |
430 | Then check that the smoke tests pass (particularly on Win32). If not, go |
431 | back and fix things. |
7277a900 |
432 | |
7277a900 |
433 | |
f6af4394 |
434 | =item * |
7277a900 |
435 | |
f6af4394 |
436 | Once smoking is okay, upload it to PAUSE. This is the point of no return. |
addebd58 |
437 | You may wish to create a .bz2 version of the tarball and upload that too. |
f6af4394 |
438 | |
210de33e |
439 | =item * |
440 | |
441 | create a tag [XXX and branches and stuff ????], e.g.: |
442 | |
443 | $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' |
444 | $ git push origin tag perl-5.10.1-RC1 |
f6af4394 |
445 | |
446 | =item * |
447 | |
448 | Mail p5p to announce it, with a quote you prepared earlier. |
449 | |
450 | =item * |
451 | |
452 | Wait 24 hours or so, then post the announcement to use.perl.org. |
addebd58 |
453 | (if you don't have access rights to post news, ask someone like Rafael to |
454 | do it for you.) |
f6af4394 |
455 | |
456 | =back |
457 | |
458 | |
459 | =head2 Making a final release |
460 | |
461 | At this point you should have a working release candidate with few or no |
462 | changes since. |
463 | |
464 | It's essentially the same procedure as for making a release candidate, but |
465 | with a whole bunch of extra post-release steps. |
466 | |
467 | =over 4 |
7277a900 |
468 | |
f6af4394 |
469 | =item * |
7277a900 |
470 | |
f6af4394 |
471 | Follow the same steps as for making a release candidate, then |
7277a900 |
472 | |
f6af4394 |
473 | =item * |
7277a900 |
474 | |
f6af4394 |
475 | Ask Jarkko to update http://www.cpan.org/src/README.html and |
476 | Rafael to update http://dev.perl.org/perl5/ |
7277a900 |
477 | |
f6af4394 |
478 | =item * |
7277a900 |
479 | |
f6af4394 |
480 | Create a new empty perlNNNdelta.pod file for the current release + 1; |
481 | see F<Porting/how_to_write_a_perldelta.pod>. |
482 | [ XXX Perhaps we should have an empty template file we can copy in. ] |
7277a900 |
483 | |
a2cba4bc |
484 | In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous |
485 | entry as 'D', then run C<perl pod/buildtoc --build-all> to update the |
486 | following files: |
7277a900 |
487 | |
f6af4394 |
488 | MANIFEST |
f6af4394 |
489 | pod/perl.pod |
a2cba4bc |
490 | win32/pod.mak |
491 | vms/descrip_mms.template |
492 | |
493 | (F<vms/descrip_mms.template> still needs a manual edit to bump the |
494 | C<perldelta.pod> entry - it would be good for someone to figure out the fix.) |
7277a900 |
495 | |
f6af4394 |
496 | and change perlNNNdelta references to the new version in these files |
7277a900 |
497 | |
f6af4394 |
498 | INSTALL |
499 | win32/Makefile.mk |
500 | win32/Makefile |
501 | Makefile.SH |
502 | README |
7277a900 |
503 | |
f6af4394 |
504 | Also, edit the previous delta file to change the C<NAME> from C<perldelta> |
505 | to C<perlNNNdelta>. |
7277a900 |
506 | |
f6af4394 |
507 | These two lists of files probably aren't exhaustive; do a recursive grep |
508 | on the previous filename to look for suitable candidates. |
7277a900 |
509 | |
f6af4394 |
510 | (see 16410843ea for an example). |
7277a900 |
511 | |
f6af4394 |
512 | =item * |
7277a900 |
513 | |
dc0a62a1 |
514 | If this was a maintenance release, then edit F<Porting/mergelog> to change |
515 | all the C<d> (deferred) flags to C<.> (needs review). |
516 | |
517 | |
518 | =item * |
519 | |
addebd58 |
520 | If this was a major release, then |
521 | |
522 | =over |
523 | |
524 | =item * |
525 | |
526 | bump the version, e.g. 5.12.0 to 5.13.0; |
527 | |
528 | =item * |
529 | |
530 | [ XXX probably lots more stuff to do, including perldelta, |
f6af4394 |
531 | C<lib/feature.pm> ] |
7277a900 |
532 | |
f6af4394 |
533 | =item * |
7277a900 |
534 | |
addebd58 |
535 | Create a new maint branch with an empty Porting/mergelog file |
536 | [ XXX and lots of other stuff too, probably ] |
537 | |
538 | =back |
539 | |
540 | =item * |
541 | |
f6af4394 |
542 | Copy the perlNNNdelta.pod for this release into the other branches, and |
543 | remember to update these files on those branches too: |
7277a900 |
544 | |
f6af4394 |
545 | MANIFEST |
546 | pod.lst |
547 | pod/perl.pod |
548 | vms/descrip_mms.template |
549 | win32/pod.mak |
7277a900 |
550 | |
f6af4394 |
551 | (see fc5be80860 for an example). |
7277a900 |
552 | |
f6af4394 |
553 | =item * |
7277a900 |
554 | |
f6af4394 |
555 | Make sure any recent F<pod/perlhist.pod> entries are copied to |
556 | F<perlhist.pod> on other branches; typically the RC* and final entries, |
557 | e.g. |
7277a900 |
558 | |
f6af4394 |
559 | 5.8.9-RC1 2008-Nov-10 |
560 | 5.8.9-RC2 2008-Dec-06 |
561 | 5.8.9 2008-Dec-14 |
7277a900 |
562 | |
6e40fbf9 |
563 | =item * |
564 | |
565 | Remind the current maintainer of C<Module::CoreList> to push a new release |
566 | to CPAN. |
567 | |
7277a900 |
568 | =back |
569 | |
570 | =head1 SOURCE |
571 | |
f6af4394 |
572 | Based on |
573 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html, |
574 | plus a whole bunch of other sources, including private correspondence. |
7277a900 |
575 | |
576 | =cut |
577 | |