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