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