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