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 | |
84 | Make sure the correct pumpking is listed, and if this your first time, |
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 | |
f6af4394 |
282 | =item * |
7277a900 |
283 | |
f6af4394 |
284 | Update the F<Changes> file to contain the git log command which would show |
285 | all the changes in this release. You will need assume the existence of a |
286 | not-yet created tag for the forthcoming release; e.g. |
7277a900 |
287 | |
f6af4394 |
288 | git log ... perl-5.10.0..perl5.12.0 |
7277a900 |
289 | |
f6af4394 |
290 | Due to warts in the perforce-to-git migration, some branches require extra |
291 | exclusions to avoid other branches being pulled in. Make sure you have the |
292 | correct incantation: replace the not-yet-created tag with C<HEAD> and see |
293 | if git log produces roughly the right number of commits across roughly the |
294 | right time period. |
7277a900 |
295 | |
f6af4394 |
296 | =item * |
7277a900 |
297 | |
f6af4394 |
298 | Check some more build configurations, e.g. |
7277a900 |
299 | |
f6af4394 |
300 | -Duseshrplib -Dd_dosuid |
301 | make suidperl |
7277a900 |
302 | |
f6af4394 |
303 | Check that setuid installs works (for < 5.11.0 only). |
304 | XXX any other configs? |
7277a900 |
305 | |
f6af4394 |
306 | =item * |
7277a900 |
307 | |
f6af4394 |
308 | Make sure you have a PAUSE account suitable for uploading a perl release. |
309 | If you don't have a PAUSE account, then request one: |
7277a900 |
310 | |
f6af4394 |
311 | https://pause.perl.org/pause/query?ACTION=request_id |
7277a900 |
312 | |
f6af4394 |
313 | Check that your account is allowed to upload perl distros: goto |
314 | https://pause.perl.org/, login, then select 'upload file to CPAN'; there |
315 | should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas |
316 | to add your ID to the list of people allowed to upload something called |
317 | perl. |
7277a900 |
318 | |
f6af4394 |
319 | =item * |
7277a900 |
320 | |
f6af4394 |
321 | Update F<AUTHORS>, using the C<Porting/checkAUTHORS.pl> script, and if |
322 | necessary, update the script to include new alias mappings. |
7277a900 |
323 | |
f6af4394 |
324 | XXX This script is currently broken (7/2009). It needs updating to work |
325 | with git and a lack of Changes files. |
326 | |
327 | =back |
328 | |
329 | =head2 Building a release candidate |
330 | |
331 | (At this point you should already have performed the actions described in |
332 | L</"Actions prior to the first release candidate">.) |
333 | |
334 | =over 4 |
335 | |
336 | =item * |
337 | |
338 | Re-read the perldelta to try to find any embarrassing typos and thinkos; |
339 | remove any C<TODO> or C<XXX> flags; and run through pod and spell |
340 | checkers. [XXX show how] |
341 | |
342 | =item * |
343 | |
344 | Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a |
345 | final release, remove it. [ XXX how now?? see 34813 for old way ] |
346 | |
347 | =item * |
348 | |
349 | Update C<Module::Corelist>. |
350 | [XXX add how: presumably Porting/corelist.pl ] |
351 | but we need to fix that: |
352 | it has been holding perforce revisions for releases, but we can't know |
7277a900 |
353 | hashes in advance for git. We need to agree a plan to move to git tags] |
354 | |
f6af4394 |
355 | =item * |
356 | |
357 | Follow the instructions in the section L</"Building a snapshot">, then |
358 | carry on with the extra steps that follow here. |
359 | |
360 | =item * |
7277a900 |
361 | |
f6af4394 |
362 | Wait for the smoke tests to catch up with the commit which this release is |
363 | based on (or at least the last commit of any consequence). |
7277a900 |
364 | |
f6af4394 |
365 | Then check that the smoke tests pass (particularly on Win32). If not, go |
366 | back and fix things. |
7277a900 |
367 | |
7277a900 |
368 | |
f6af4394 |
369 | =item * |
7277a900 |
370 | |
f6af4394 |
371 | Once smoking is okay, upload it to PAUSE. This is the point of no return. |
372 | |
373 | XXX check whether need to upload .bz2,.meta, .readme too? |
374 | |
375 | |
376 | =item * |
377 | |
378 | Mail p5p to announce it, with a quote you prepared earlier. |
379 | |
380 | =item * |
381 | |
382 | Wait 24 hours or so, then post the announcement to use.perl.org. |
383 | |
384 | =back |
385 | |
386 | |
387 | =head2 Making a final release |
388 | |
389 | At this point you should have a working release candidate with few or no |
390 | changes since. |
391 | |
392 | It's essentially the same procedure as for making a release candidate, but |
393 | with a whole bunch of extra post-release steps. |
394 | |
395 | =over 4 |
7277a900 |
396 | |
f6af4394 |
397 | =item * |
7277a900 |
398 | |
f6af4394 |
399 | Follow the same steps as for making a release candidate, then |
7277a900 |
400 | |
f6af4394 |
401 | =item * |
7277a900 |
402 | |
f6af4394 |
403 | Ask Jarkko to update http://www.cpan.org/src/README.html and |
404 | Rafael to update http://dev.perl.org/perl5/ |
7277a900 |
405 | |
7277a900 |
406 | |
f6af4394 |
407 | =item * |
7277a900 |
408 | |
f6af4394 |
409 | create a tag [XXX and branches and stuff?] |
410 | [ XXX expand this ] |
7277a900 |
411 | |
f6af4394 |
412 | =item * |
7277a900 |
413 | |
f6af4394 |
414 | [ XXX disarm any patchlevel.h stuff ??? ] |
7277a900 |
415 | |
f6af4394 |
416 | =item * |
7277a900 |
417 | |
f6af4394 |
418 | Create a new empty perlNNNdelta.pod file for the current release + 1; |
419 | see F<Porting/how_to_write_a_perldelta.pod>. |
420 | [ XXX Perhaps we should have an empty template file we can copy in. ] |
7277a900 |
421 | |
a2cba4bc |
422 | In addition, edit F<pod.lst>, adding the new entry as 'D', and unmark previous |
423 | entry as 'D', then run C<perl pod/buildtoc --build-all> to update the |
424 | following files: |
7277a900 |
425 | |
f6af4394 |
426 | MANIFEST |
f6af4394 |
427 | pod/perl.pod |
a2cba4bc |
428 | win32/pod.mak |
429 | vms/descrip_mms.template |
430 | |
431 | (F<vms/descrip_mms.template> still needs a manual edit to bump the |
432 | C<perldelta.pod> entry - it would be good for someone to figure out the fix.) |
7277a900 |
433 | |
f6af4394 |
434 | and change perlNNNdelta references to the new version in these files |
7277a900 |
435 | |
f6af4394 |
436 | INSTALL |
437 | win32/Makefile.mk |
438 | win32/Makefile |
439 | Makefile.SH |
440 | README |
7277a900 |
441 | |
f6af4394 |
442 | Also, edit the previous delta file to change the C<NAME> from C<perldelta> |
443 | to C<perlNNNdelta>. |
7277a900 |
444 | |
f6af4394 |
445 | These two lists of files probably aren't exhaustive; do a recursive grep |
446 | on the previous filename to look for suitable candidates. |
7277a900 |
447 | |
f6af4394 |
448 | (see 16410843ea for an example). |
7277a900 |
449 | |
f6af4394 |
450 | =item * |
7277a900 |
451 | |
f6af4394 |
452 | If this was major release, bump the version, e.g. 5.12.0 to 5.13.0 |
453 | [ XXX probably more complex stuff to do, including perldelta, |
454 | C<lib/feature.pm> ] |
7277a900 |
455 | |
f6af4394 |
456 | =item * |
7277a900 |
457 | |
f6af4394 |
458 | Copy the perlNNNdelta.pod for this release into the other branches, and |
459 | remember to update these files on those branches too: |
7277a900 |
460 | |
f6af4394 |
461 | MANIFEST |
462 | pod.lst |
463 | pod/perl.pod |
464 | vms/descrip_mms.template |
465 | win32/pod.mak |
7277a900 |
466 | |
f6af4394 |
467 | (see fc5be80860 for an example). |
7277a900 |
468 | |
f6af4394 |
469 | =item * |
7277a900 |
470 | |
f6af4394 |
471 | Make sure any recent F<pod/perlhist.pod> entries are copied to |
472 | F<perlhist.pod> on other branches; typically the RC* and final entries, |
473 | e.g. |
7277a900 |
474 | |
f6af4394 |
475 | 5.8.9-RC1 2008-Nov-10 |
476 | 5.8.9-RC2 2008-Dec-06 |
477 | 5.8.9 2008-Dec-14 |
7277a900 |
478 | |
479 | =back |
480 | |
481 | =head1 SOURCE |
482 | |
f6af4394 |
483 | Based on |
484 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html, |
485 | plus a whole bunch of other sources, including private correspondence. |
7277a900 |
486 | |
487 | =cut |
488 | |