Commit | Line | Data |
---|---|---|
49781f4a AB |
1 | =encoding utf8 |
2 | ||
7277a900 GS |
3 | =head1 NAME |
4 | ||
5 | release_managers_guide - Releasing a new version of perl 5.x | |
6 | ||
dc0a4df9 DM |
7 | Note that things change at each release, so there may be new things not |
8 | covered here, or tools may need updating. | |
9 | ||
c78277ad DR |
10 | =head1 MAKING A CHECKLIST |
11 | ||
12 | If you are preparing to do a release, you can run the | |
13 | F<Porting/make-rmg-checklist> script to generate a new version of this | |
14 | document that starts with a checklist for your release. | |
15 | ||
16 | This script is run as: | |
17 | ||
18 | perl Porting/make-rmg-checklist \ | |
19 | --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod | |
20 | ||
21 | You can also pass the C<--html> flag to generate an HTML document instead of | |
22 | POD. | |
f6af4394 | 23 | |
0056d3d2 DR |
24 | perl Porting/make-rmg-checklist --html \ |
25 | --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html | |
26 | ||
7277a900 GS |
27 | =head1 SYNOPSIS |
28 | ||
f6af4394 | 29 | This document describes the series of tasks required - some automatic, some |
dc0a4df9 DM |
30 | manual - to produce a perl release of some description, be that a release |
31 | candidate, or final, numbered release of maint or blead. | |
f6af4394 | 32 | |
8c35d285 | 33 | The release process has traditionally been executed by the current |
ee76d676 JV |
34 | pumpking. Blead releases from 5.11.0 forward are made each month on the |
35 | 20th by a non-pumpking release engineer. The release engineer roster | |
36 | and schedule can be found in Porting/release_schedule.pod. | |
7277a900 | 37 | |
8c35d285 JV |
38 | This document both helps as a check-list for the release engineer |
39 | and is a base for ideas on how the various tasks could be automated | |
40 | or distributed. | |
7277a900 | 41 | |
da571fa1 | 42 | The checklist of a typical release cycle is as follows: |
f6af4394 | 43 | |
636a1918 | 44 | (5.10.1 is released, and post-release actions have been done) |
f6af4394 DM |
45 | |
46 | ...time passes... | |
47 | ||
f6af4394 DM |
48 | a few weeks before the release, a number of steps are performed, |
49 | including bumping the version to 5.10.2 | |
636a1918 DM |
50 | |
51 | ...a few weeks passes... | |
46743ef7 | 52 | |
f6af4394 DM |
53 | perl-5.10.2-RC1 is released |
54 | ||
55 | perl-5.10.2 is released | |
56 | ||
57 | post-release actions are performed, including creating new | |
c5b87fed | 58 | perldelta.pod |
f6af4394 DM |
59 | |
60 | ... the cycle continues ... | |
7277a900 | 61 | |
dc0a4df9 | 62 | |
7277a900 GS |
63 | =head1 DETAILS |
64 | ||
6a958a95 DM |
65 | Some of the tasks described below apply to all four types of |
66 | release of Perl. (blead, RC, final release of maint, final | |
8c35d285 JV |
67 | release of blead). Some of these tasks apply only to a subset |
68 | of these release types. If a step does not apply to a given | |
69 | type of release, you will see a notation to that effect at | |
70 | the beginning of the step. | |
71 | ||
dc0a4df9 | 72 | |
8c35d285 JV |
73 | =head2 Release types |
74 | ||
75 | =over 4 | |
76 | ||
8c35d285 JV |
77 | =item Release Candidate (RC) |
78 | ||
d60a1044 DM |
79 | A release candidate is an attempt to produce a tarball that is a close as |
80 | possible to the final release. Indeed, unless critical faults are found | |
81 | during the RC testing, the final release will be identical to the RC | |
82 | barring a few minor fixups (updating the release date in F<perlhist.pod>, | |
83 | removing the RC status from F<patchlevel.h>, etc). If faults are found, | |
84 | then the fixes should be put into a new release candidate, never directly | |
85 | into a final release. | |
8c35d285 | 86 | |
6a958a95 DM |
87 | |
88 | =item Stable/Maint release (MAINT). | |
89 | ||
90 | A release with an even version number, and subversion number > 0, such as | |
91 | 5.14.1 or 5.14.2. | |
8c35d285 JV |
92 | |
93 | At this point you should have a working release candidate with few or no | |
94 | changes since. | |
95 | ||
96 | It's essentially the same procedure as for making a release candidate, but | |
97 | with a whole bunch of extra post-release steps. | |
98 | ||
6a958a95 DM |
99 | =item A blead point release (BLEAD-POINT) |
100 | ||
101 | A release with an odd version number, such as 5.15.0 or 5.15.1. | |
102 | ||
103 | This isn't for production, so it has less stability requirements than for | |
104 | other release types, and isn't preceded by RC releases. Other than that, | |
105 | it is similar to a MAINT release. | |
106 | ||
107 | =item Blead final release (BLEAD-FINAL) | |
108 | ||
109 | A release with an even version number, and subversion number == 0, such as | |
dc0a4df9 | 110 | 5.14.0. That is to say, it's the big new release once per year. |
8c35d285 JV |
111 | |
112 | It's essentially the same procedure as for making a release candidate, but | |
6a958a95 | 113 | with a whole bunch of extra post-release steps, even more than for MAINT. |
8c35d285 JV |
114 | |
115 | =back | |
7277a900 | 116 | |
da571fa1 | 117 | =for checklist begin |
dc0a4df9 | 118 | |
fd838dcf JV |
119 | =head2 Prerequisites |
120 | ||
121 | Before you can make an official release of perl, there are a few | |
122 | hoops you need to jump through: | |
123 | ||
00c28750 | 124 | =head3 PAUSE account with pumpkin status |
8c35d285 | 125 | |
fd838dcf JV |
126 | Make sure you have a PAUSE account suitable for uploading a perl release. |
127 | If you don't have a PAUSE account, then request one: | |
128 | ||
129 | https://pause.perl.org/pause/query?ACTION=request_id | |
130 | ||
9a3b7d40 FR |
131 | Check that your account is allowed to upload perl distros: go to |
132 | L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that | |
133 | your PAUSE ID is listed there. If not, ask Andreas KE<0xf6>nig to add your ID | |
134 | to the list of people allowed to upload something called perl. You can find | |
135 | Andreas' email address at: | |
4d2c8158 | 136 | |
fd838dcf JV |
137 | https://pause.perl.org/pause/query?ACTION=pause_04imprint |
138 | ||
00c28750 | 139 | =head3 search.cpan.org pumpkin status |
fdabea7a JV |
140 | |
141 | Make sure that search.cpan.org knows that you're allowed to upload | |
142 | perl distros. Contact Graham Barr to make sure that you're on the right | |
143 | list. | |
144 | ||
a72d816c RS |
145 | =head3 rt.perl.org update access |
146 | ||
147 | Make sure you have permission to close tickets on L<http://rt.perl.org/> | |
148 | so you can respond to bug report as necessary during your stint. If you | |
149 | don't, make an account (if you don't have one) and contact the pumpking | |
150 | with your username to get ticket-closing permission. | |
151 | ||
da571fa1 | 152 | =head3 git checkout and commit bit |
fd838dcf JV |
153 | |
154 | You will need a working C<git> installation, checkout of the perl | |
155 | git repository and perl commit bit. For information about working | |
c222ef46 | 156 | with perl and git, see F<pod/perlgit.pod>. |
fd838dcf JV |
157 | |
158 | If you are not yet a perl committer, you won't be able to make a | |
159 | release. Have a chat with whichever evil perl porter tried to talk | |
160 | you into the idea in the first place to figure out the best way to | |
161 | resolve the issue. | |
162 | ||
845a9291 MM |
163 | =head3 git clone of https://github.com/perlorg/perlweb |
164 | ||
165 | For updating the L<http://dev.perl.org> web pages, either a Github account or | |
166 | sweet-talking somebody with a Github account into obedience is needed. This | |
167 | is only needed on the day of the release or shortly afterwards. | |
168 | ||
da571fa1 | 169 | =for checklist skip RC |
f6af4394 | 170 | |
da571fa1 | 171 | =head3 Quotation for release announcement epigraph |
f6af4394 | 172 | |
b1288acc | 173 | I<SKIP this step for RC> |
f6af4394 | 174 | |
6a958a95 | 175 | For all except an RC release of perl, you will need a quotation |
b1288acc | 176 | to use as an epigraph to your release announcement. |
46743ef7 | 177 | |
2e831dfd | 178 | =head2 Building a release - advance actions |
8c35d285 | 179 | |
9c39c536 A |
180 | The work of building a release candidate for an even numbered release |
181 | (BLEAD-FINAL) of perl generally starts several weeks before the first | |
182 | release candidate. Some of the following steps should be done regularly, | |
183 | but all I<must> be done in the run up to a release. | |
7277a900 | 184 | |
dc0a4df9 | 185 | =head3 dual-life CPAN module synchronisation |
f6af4394 | 186 | |
1d84c074 | 187 | To see which core distro versions differ from the current CPAN versions: |
f6af4394 | 188 | |
1d84c074 | 189 | $ ./perl -Ilib Porting/core-cpan-diff -x -a |
7277a900 | 190 | |
1d84c074 JL |
191 | Passing C<-u cpan> (and maybe C<-u undef>) will probably be helpful, since |
192 | those are the only types of distributions that you can actually affect as a | |
193 | perl release manager (as opposed to a CPAN module maintainer). | |
7277a900 | 194 | |
1d84c074 JL |
195 | You can also run an actual diff of the contents of the modules, comparing core |
196 | to CPAN, to ensure that there were no erroneous/extraneous changes that need to | |
197 | be dealt with. You do this by not passing the C<-x> option: | |
7277a900 | 198 | |
1d84c074 JL |
199 | $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs |
200 | ||
201 | then fix the core, or cajole CPAN authors as appropriate. See also the C<-d> | |
202 | and C<-v> options for more detail (and the C<-u> option as mentioned above). | |
203 | You'll probably want to use the C<-c cachedir> option to avoid repeated CPAN | |
204 | downloads and may want to use C<-m file:///mirror/path> if you made a local | |
205 | CPAN mirror. Note that a minicpan mirror won't actually work, but can provide a | |
206 | good first pass to quickly get a list of modules which definitely haven't | |
207 | changed, to avoid having to download absolutely everything. | |
7277a900 | 208 | |
6a958a95 | 209 | If you are making a MAINT release, run C<core-cpan-diff> on both blead and |
636a1918 DM |
210 | maint, then diff the two outputs. Compare this with what you expect, and if |
211 | necessary, fix things up. For example, you might think that both blead | |
212 | and maint are synchronised with a particular CPAN module, but one might | |
213 | have some extra changes. | |
214 | ||
9c39c536 A |
215 | =head3 How to sync a CPAN module with a cpan/ distro |
216 | ||
217 | =over 4 | |
218 | ||
219 | =item * | |
220 | ||
221 | Fetch the most recent version from CPAN. | |
222 | ||
223 | =item * | |
224 | ||
225 | Unpack the retrieved tarball. Rename the old directory; rename the new | |
226 | directory to the original name. | |
227 | ||
228 | =item * | |
229 | ||
9e40a104 | 230 | Restore any F<.gitignore> file. This can be done by issuing |
02cbdfef | 231 | C<git checkout .gitignore> in the F<cpan/Distro> directory. |
9c39c536 A |
232 | |
233 | =item * | |
234 | ||
235 | Remove files we do not need. That is, remove any files that match the | |
02cbdfef | 236 | entries in C<@IGNORE> in F<Porting/Maintainer.pl>, and anything that |
9c39c536 A |
237 | matches the C<EXCLUDED> section of the distro's entry in the C<%Modules> |
238 | hash. | |
239 | ||
240 | =item * | |
241 | ||
242 | Restore any files mentioned in the C<CUSTOMIZED> section, using | |
243 | C<git checkout>. Make any new customizations if necessary. Also, | |
244 | restore any files that are mentioned in C<@IGNORE>, but were checked | |
245 | in in the repository anyway. | |
246 | ||
247 | =item * | |
248 | ||
249 | For any new files in the distro, determine whether they are needed. | |
250 | If not, delete them, and list them in either C<EXCLUDED> or C<@INGORE>. | |
251 | Otherwise, add them to C<MANIFEST>, and run C<git add> to add the files | |
252 | to the repository. | |
253 | ||
254 | =item * | |
255 | ||
256 | For any files that are gone, remove them from C<MANIFEST>, and use | |
257 | C<git rm> to tell git the files will be gone. | |
258 | ||
259 | =item * | |
260 | ||
261 | If the C<MANIFEST> file was changed in any of the previous steps, run | |
262 | C<perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST>. | |
263 | ||
264 | =item * | |
265 | ||
266 | For any files that have an execute bit set, either remove the execute | |
02cbdfef | 267 | bit, or edit F<Porting/exec-bit.txt> |
9c39c536 A |
268 | |
269 | =item * | |
270 | ||
0b7399e1 | 271 | Run C<make> (or C<nmake> on Windows), see if C<perl> compiles. |
9c39c536 A |
272 | |
273 | =item * | |
274 | ||
275 | Run the tests for the package. | |
276 | ||
277 | =item * | |
278 | ||
02cbdfef | 279 | Run the tests in F<t/porting>. |
9c39c536 A |
280 | |
281 | =item * | |
282 | ||
02cbdfef | 283 | Update the C<DISTRIBUTION> entry in F<Porting/Maintainers.pl>. |
9c39c536 A |
284 | |
285 | =item * | |
286 | ||
287 | Run a full configure/build/test cycle. | |
288 | ||
289 | =item * | |
290 | ||
291 | If everything is ok, commit the changes. | |
292 | ||
293 | =back | |
294 | ||
295 | For entries with a non-simple C<FILES> section, or with a C<MAP>, you | |
296 | may have to take more steps than listed above. | |
297 | ||
02cbdfef | 298 | F<Porting/sync-with-cpan> is a script that automates most of the steps |
0b7399e1 SH |
299 | above; but see the comments at the beginning of the file. In particular, |
300 | it has not yet been exercised on Windows, but will certainly require a set | |
301 | of Unix tools such as Cygwin, and steps that run C<make> will need to run | |
302 | C<nmake> instead. | |
9c39c536 | 303 | |
dc0a4df9 DM |
304 | |
305 | =head3 dual-life CPAN module stability | |
7277a900 | 306 | |
f6af4394 | 307 | Ensure dual-life CPAN modules are stable, which comes down to: |
7277a900 GS |
308 | |
309 | for each module that fails its regression tests on $current | |
f6af4394 DM |
310 | did it fail identically on $previous? |
311 | if yes, "SEP" (Somebody Else's Problem) | |
312 | else work out why it failed (a bisect is useful for this) | |
7277a900 GS |
313 | |
314 | attempt to group failure causes | |
315 | ||
316 | for each failure cause | |
f6af4394 DM |
317 | is that a regression? |
318 | if yes, figure out how to fix it | |
319 | (more code? revert the code that broke it) | |
320 | else | |
321 | (presumably) it's relying on something un-or-under-documented | |
322 | should the existing behaviour stay? | |
323 | yes - goto "regression" | |
324 | no - note it in perldelta as a significant bugfix | |
325 | (also, try to inform the module's author) | |
1aff5354 | 326 | |
dc0a4df9 | 327 | |
00c28750 | 328 | =head3 monitor smoke tests for failures |
7277a900 | 329 | |
5157df7a | 330 | Similarly, monitor the smoking of core tests, and try to fix. See |
c840542b MB |
331 | L<http://doc.procura.nl/smoke/index.html> and L<http://perl5.test-smoke.org/> |
332 | for a summary. See also | |
5157df7a AB |
333 | L<http://www.nntp.perl.org/group/perl.daily-build.reports/> which has |
334 | the raw reports. | |
7277a900 | 335 | |
636a1918 DM |
336 | Similarly, monitor the smoking of perl for compiler warnings, and try to |
337 | fix. | |
338 | ||
dc0a4df9 | 339 | |
00c28750 | 340 | =head3 update perldelta |
636a1918 | 341 | |
f6af4394 | 342 | Get perldelta in a mostly finished state. |
db3f805e | 343 | |
04c2c53e | 344 | Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that |
636a1918 DM |
345 | every section it lists is, if necessary, populated and complete. Copy |
346 | edit the whole document. | |
f6af4394 | 347 | |
f6af4394 | 348 | |
dc0a4df9 DM |
349 | =head3 Bump the version number |
350 | ||
30f926b5 JL |
351 | Do not do this yet for a BLEAD-POINT release! You will do this at the end of |
352 | the release process. | |
353 | ||
dc0a4df9 | 354 | Increase the version number (e.g. from 5.12.0 to 5.12.1). |
04dbb930 | 355 | |
30f926b5 | 356 | For a release candidate for a stable perl, this should happen a week or two |
04dbb930 DG |
357 | before the first release candidate to allow sufficient time for testing and |
358 | smoking with the target version built into the perl executable. For | |
359 | subsequent release candidates and the final release, it it not necessary to | |
360 | bump the version further. | |
f6af4394 | 361 | |
8b2227e6 | 362 | There is a tool to semi-automate this process: |
f6af4394 | 363 | |
8b2227e6 | 364 | $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1 |
f6af4394 | 365 | |
8b2227e6 LB |
366 | Remember that this tool is largely just grepping for '5.10.0' or whatever, |
367 | so it will generate false positives. Be careful not change text like | |
368 | "this was fixed in 5.10.0"! | |
ceb7f800 | 369 | |
8b2227e6 | 370 | Use git status and git diff to select changes you want to keep. |
ceb7f800 | 371 | |
f6af4394 DM |
372 | Be particularly careful with F<INSTALL>, which contains a mixture of |
373 | C<5.10.0>-type strings, some of which need bumping on every release, and | |
e03f126c Z |
374 | some of which need to be left unchanged. |
375 | The line in F<INSTALL> about "is binary incompatible with" requires a | |
376 | correct choice of earlier version to declare incompatibility with. | |
377 | ||
6a958a95 DM |
378 | When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the |
379 | C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version | |
380 | you're releasing, unless you're | |
e43cb88f | 381 | absolutely sure the release you're about to make is 100% binary compatible |
6a958a95 | 382 | to an earlier release. When releasing a MAINT perl version, the C<PERL_API_*> |
e43cb88f TM |
383 | constants C<MUST NOT> be changed as we aim to guarantee binary compatibility |
384 | in maint branches. | |
45ce9531 | 385 | |
17163f85 DM |
386 | After editing, regenerate uconfig.h (this must be run on a system with a |
387 | /bin/sh available): | |
22be9667 | 388 | |
17163f85 | 389 | $ perl regen/uconfig_h.pl |
22be9667 | 390 | |
78957677 JL |
391 | This might not cause any new changes. |
392 | ||
22be9667 JV |
393 | Test your changes: |
394 | ||
17163f85 | 395 | $ git clean -xdf # careful if you don't have local files to keep! |
22be9667 JV |
396 | $ ./Configure -des -Dusedevel |
397 | $ make | |
398 | $ make test | |
399 | ||
54356a6f JV |
400 | Commit your changes: |
401 | ||
04abd20e | 402 | $ git status |
e91bd5c0 LB |
403 | $ git diff |
404 | B<review the delta carefully> | |
54356a6f JV |
405 | |
406 | $ git commit -a -m 'Bump the perl version in various places for 5.x.y' | |
dc0a62a1 | 407 | |
21768cb3 | 408 | At this point you may want to compare the commit with a previous bump to |
eb92bade | 409 | see if they look similar. See commit 0e79a3d1bc for an example of a |
21768cb3 FC |
410 | previous version bump. |
411 | ||
dc0a4df9 DM |
412 | When the version number is bumped, you should also update Module::CoreList |
413 | (as described below in L<"update Module::CoreList">) to reflect the new | |
81fc59ef DG |
414 | version number. |
415 | ||
dc0a4df9 DM |
416 | |
417 | =head3 update INSTALL | |
dc0a62a1 DM |
418 | |
419 | Review and update INSTALL to account for the change in version number; | |
420 | in particular, the "Coexistence with earlier versions of perl 5" section. | |
421 | ||
6a958a95 DM |
422 | Be particularly careful with the section "Upgrading from 5.X.Y or earlier". |
423 | The "X.Y" needs to be changed to the most recent version that we are | |
424 | I<not> binary compatible with. | |
425 | ||
426 | For MAINT and BLEAD-FINAL releases, this needs to refer to the last | |
427 | release in the previous development cycle (so for example, for a 5.14.x | |
428 | release, this would be 5.13.11). | |
429 | ||
430 | For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT | |
431 | release (so for 5.15.3 this would be 5.15.2). | |
432 | ||
dc0a4df9 | 433 | =head3 Check more build configurations |
b82efa27 | 434 | |
d8fc5aa0 DR |
435 | Try running the full test suite against multiple Perl configurations. Here are |
436 | some sets of Configure flags you can try: | |
52a66c2c | 437 | |
d8fc5aa0 | 438 | =over 4 |
7277a900 | 439 | |
d8fc5aa0 DR |
440 | =item * |
441 | ||
442 | C<-Duseshrplib -Dusesitecustomize> | |
443 | ||
444 | =item * | |
445 | ||
446 | C<-Duserelocatableinc> | |
447 | ||
448 | =item * | |
449 | ||
450 | C<-Dusethreads> | |
451 | ||
452 | =back | |
7277a900 | 453 | |
d8fc5aa0 DR |
454 | If you have multiple compilers on your machine, you might also consider |
455 | compiling with C<-Dcc=$other_compiler>. | |
dc0a4df9 DM |
456 | |
457 | =head3 update perlport | |
7277a900 | 458 | |
347f5124 RGS |
459 | L<perlport> has a section currently named I<Supported Platforms> that |
460 | indicates which platforms are known to build in the current release. | |
461 | If necessary update the list and the indicated version number. | |
462 | ||
6a958a95 DM |
463 | |
464 | ||
2e831dfd DM |
465 | =head2 Building a release - on the day |
466 | ||
b1288acc DM |
467 | This section describes the actions required to make a release |
468 | that are performed on the actual day. | |
2e831dfd | 469 | |
2e831dfd | 470 | |
dc0a4df9 | 471 | =head3 re-check earlier actions |
2e831dfd | 472 | |
dc0a4df9 | 473 | Review all the actions in the previous section, |
2e831dfd DM |
474 | L<"Building a release - advance actions"> to ensure they are all done and |
475 | up-to-date. | |
476 | ||
dc0a4df9 | 477 | |
ff721450 JL |
478 | =head3 create a release branch |
479 | ||
480 | For BLEAD-POINT releases, making a release from a release branch avoids the | |
481 | need to freeze blead during the release. This is less important for | |
482 | BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in | |
483 | those cases. Create the branch by running | |
484 | ||
485 | git checkout -b release-5.xx.yy | |
486 | ||
487 | ||
dc0a4df9 | 488 | =head3 finalize perldelta |
04dbb930 | 489 | |
04dbb930 | 490 | Finalize the perldelta. In particular, fill in the Acknowledgements |
548e9a3a | 491 | section, which can be generated with something like: |
38195a8c | 492 | |
548e9a3a | 493 | $ perl Porting/acknowledgements.pl v5.15.0..HEAD |
ef86391b | 494 | |
a0db33fe DM |
495 | Re-read the perldelta to try to find any embarrassing typos and thinkos; |
496 | remove any C<TODO> or C<XXX> flags; update the "Known Problems" section | |
497 | with any serious issues for which fixes are not going to happen now; and | |
498 | run through pod and spell checkers, e.g. | |
2e831dfd | 499 | |
c5b87fed FR |
500 | $ podchecker -warnings -warnings pod/perldelta.pod |
501 | $ spell pod/perldelta.pod | |
2e831dfd | 502 | |
a0db33fe DM |
503 | Also, you may want to generate and view an HTML version of it to check |
504 | formatting, e.g. | |
2e831dfd | 505 | |
3f894c2d | 506 | $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html |
2e831dfd | 507 | |
38195a8c DG |
508 | Another good HTML preview option is http://search.cpan.org/pod2html |
509 | ||
510 | If you make changes, be sure to commit them. | |
511 | ||
da571fa1 DR |
512 | =for checklist skip BLEAD-POINT MAINT RC |
513 | ||
a03432f2 KW |
514 | =head3 remove stale perldeltas |
515 | ||
516 | For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas | |
517 | from the BLEAD-POINT releases since the previous BLEAD_FINAL should have | |
518 | now been consolidated into the current perldelta, and hence are now just | |
519 | useless clutter. They can be removed using: | |
520 | ||
521 | $ git rm <file1> <file2> ... | |
522 | ||
523 | For example, for RC0 of 5.16.0: | |
524 | ||
525 | $ cd pod | |
526 | $ git rm perldelta515*.pod | |
527 | ||
ace68858 NC |
528 | All mention to them should also be removed. Edit F<pod/perl.pod> to remove |
529 | them from its table of contents, then run F<Porting/pod_rules.pl> to | |
530 | propagate your changes there into all the other files that mention them | |
531 | (including F<MANIFEST>). You'll need to C<git add> the files that it changes. | |
a03432f2 KW |
532 | |
533 | Then build a clean perl and do a full test | |
534 | ||
535 | $ git status | |
536 | $ git clean -dxf | |
537 | $ ./Configure -Dusedevel -des | |
538 | $ make | |
539 | $ make test | |
540 | ||
541 | Once all tests pass, commit your changes. | |
dc0a4df9 DM |
542 | |
543 | =head3 build a clean perl | |
8c35d285 | 544 | |
a03432f2 KW |
545 | If you skipped the previous step (removing the stale perldeltas) |
546 | make sure you have a gitwise-clean perl directory (no modified files, | |
a0db33fe | 547 | unpushed commits etc): |
8c35d285 | 548 | |
a0db33fe | 549 | $ git status |
24c5e187 | 550 | $ git clean -dxf |
8c35d285 | 551 | |
dc0a4df9 | 552 | then configure and build perl so that you have a Makefile and porting tools: |
8c35d285 | 553 | |
52a66c2c | 554 | $ ./Configure -Dusedevel -des && make |
8c35d285 | 555 | |
dc0a4df9 | 556 | =head3 update Module::CoreList |
8c35d285 | 557 | |
1bac61bb | 558 | Update C<Module::CoreList> with module version data for the new release. |
bfadf2ba | 559 | |
6a958a95 | 560 | Note that if this is a MAINT release, you should run the following actions |
1bac61bb | 561 | from the maint branch, but commit the C<CoreList.pm> changes in |
a9d1f3db LB |
562 | I<blead> and subsequently cherry-pick any releases since the last |
563 | maint release and then your recent commit. XXX need a better example | |
bfadf2ba | 564 | |
a0db33fe | 565 | F<corelist.pl> uses ftp.funet.fi to verify information about dual-lived |
218a07e7 SH |
566 | modules on CPAN. It can use a full, local CPAN mirror and/or fall back |
567 | on HTTP::Tiny to fetch package metadata remotely. | |
bfadf2ba JV |
568 | |
569 | (If you'd prefer to have a full CPAN mirror, see | |
570 | http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN) | |
571 | ||
a0db33fe | 572 | Then change to your perl checkout, and if necessary, |
bfadf2ba | 573 | |
595f83ae | 574 | $ make |
bfadf2ba | 575 | |
cacc980b | 576 | If this is not the first update for this version (e.g. if it was updated |
81fc59ef | 577 | when the version number was originally bumped), first edit |
d5bddf6e | 578 | F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing |
2ce7d676 RGS |
579 | entries for this version from the C<%released> and C<%version> hashes: |
580 | they will have a key like C<5.010001> for 5.10.1. | |
52a66c2c DM |
581 | |
582 | XXX the edit-in-place functionality of Porting/corelist.pl should | |
583 | be fixed to handle this automatically. | |
584 | ||
bf8ea215 | 585 | Then, If you have a local CPAN mirror, run: |
bfadf2ba | 586 | |
bfadf2ba JV |
587 | $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror |
588 | ||
589 | Otherwise, run: | |
590 | ||
bfadf2ba JV |
591 | $ ./perl -Ilib Porting/corelist.pl cpan |
592 | ||
52a66c2c | 593 | This will chug for a while, possibly reporting various warnings about |
2a720090 | 594 | badly-indexed CPAN modules unrelated to the modules actually in core. |
2ce7d676 | 595 | Assuming all goes well, it will update |
d5bddf6e | 596 | F<dist/Module-CoreList/lib/Module/CoreList.pm>. |
bfadf2ba JV |
597 | |
598 | Check that file over carefully: | |
599 | ||
d5bddf6e | 600 | $ git diff dist/Module-CoreList/lib/Module/CoreList.pm |
bfadf2ba | 601 | |
da571fa1 DR |
602 | =head4 Bump C<$Module::CoreList::VERSION> |
603 | ||
00c28750 | 604 | If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for |
bfadf2ba JV |
605 | every RC; in RC1, bump the version to a new clean number that will |
606 | appear in the final release, and leave as-is for the later RCs and final). | |
9709cbd8 FC |
607 | It may also happen that C<Module::CoreList> has been modified in blead, and |
608 | hence has a new version number already. (But make sure it is not the same | |
609 | number as a CPAN release.) | |
bfadf2ba JV |
610 | |
611 | Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> | |
612 | entry, as that is likely to reflect the previous version number. | |
613 | ||
6fb18cd5 FR |
614 | =head4 Bump C<$Module::CoreList::TieHashDelta::VERSION> |
615 | ||
616 | C<$Module::CoreList::TieHashDelta::VERSION> should always be equal to | |
617 | C<$Module::CoreList::VERSION>. Make sure the two versions match before | |
618 | proceeding. | |
619 | ||
03708946 FR |
620 | Edit the version number in the new |
621 | C<< 'Module::CoreList::TieHashDelta' => 'X.YZ' >> entry, as that is likely to | |
622 | reflect the previous version number. | |
623 | ||
00c28750 DR |
624 | =head4 Bump version in Module::CoreList F<Changes> |
625 | ||
cb9af4c0 AB |
626 | Also edit Module::CoreList's new version number in its F<Changes> |
627 | file. | |
e8c01f92 | 628 | |
00c28750 DR |
629 | =head4 Add Module::CoreList version bump to perldelta |
630 | ||
70855f8b FC |
631 | Add a perldelta entry for the new Module::CoreList version. |
632 | ||
da571fa1 DR |
633 | =for checklist skip RC |
634 | ||
48100be1 | 635 | =head4 Update C<%Module::CoreList::released> and C<CAVEATS> |
da571fa1 | 636 | |
a0db33fe | 637 | In addition, if this is a final release (rather than a release candidate): |
bfadf2ba JV |
638 | |
639 | =over 4 | |
640 | ||
641 | =item * | |
642 | ||
643 | Update this version's entry in the C<%released> hash with today's date. | |
644 | ||
645 | =item * | |
646 | ||
647 | Make sure that the script has correctly updated the C<CAVEATS> section | |
688b7920 A |
648 | (Note, the C<CAVEATS> section is in |
649 | F<dist/Module-CoreList/lib/Module/CoreList.pod>) | |
bfadf2ba JV |
650 | |
651 | =back | |
652 | ||
00c28750 DR |
653 | =head4 Commit Module::CoreList changes |
654 | ||
bfadf2ba | 655 | Finally, commit the new version of Module::CoreList: |
6a958a95 | 656 | (unless this is for MAINT; in which case commit it to blead first, then |
a0db33fe | 657 | cherry-pick it back). |
bfadf2ba | 658 | |
688b7920 | 659 | $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod |
bfadf2ba | 660 | |
da571fa1 | 661 | =for checklist skip RC |
dc0a4df9 | 662 | |
dc0a4df9 | 663 | =head3 update perlhist.pod |
a0db33fe | 664 | |
e8a7a70e | 665 | I<You MUST SKIP this step for a RC release> |
a0db33fe | 666 | |
e8a7a70e JV |
667 | Add an entry to F<pod/perlhist.pod> with the release date, e.g.: |
668 | ||
669 | David 5.10.1 2009-Aug-06 | |
a0db33fe DM |
670 | |
671 | Make sure that the correct pumpking is listed in the left-hand column, and | |
672 | if this is the first release under the stewardship of a new pumpking, make | |
673 | sure that his or her name is listed in the section entitled | |
674 | C<THE KEEPERS OF THE PUMPKIN>. | |
675 | ||
56e2d9fb | 676 | I<If you're making a BLEAD-FINAL release>, also update the "SELECTED |
bd4ce907 RS |
677 | RELEASE SIZES" section with the output of |
678 | F<Porting/perlhist_calculate.pl>. | |
679 | ||
a0db33fe DM |
680 | Be sure to commit your changes: |
681 | ||
682 | $ git commit -m 'add new release to perlhist' pod/perlhist.pod | |
8c35d285 | 683 | |
da571fa1 | 684 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
685 | |
686 | =head3 update patchlevel.h | |
8c35d285 | 687 | |
6a958a95 | 688 | I<You MUST SKIP this step for a BLEAD-POINT release> |
d7eb1120 | 689 | |
a42352ee DM |
690 | Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is |
691 | a final release, remove it. For example: | |
d7eb1120 DM |
692 | |
693 | static const char * const local_patches[] = { | |
694 | NULL | |
695 | + ,"RC1" | |
696 | PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ | |
697 | ||
698 | Be sure to commit your change: | |
699 | ||
700 | $ git commit -m 'bump version to RCnnn' patchlevel.h | |
701 | ||
dc0a4df9 DM |
702 | |
703 | =head3 build, test and check a fresh perl | |
d7eb1120 | 704 | |
a0db33fe DM |
705 | Build perl, then make sure it passes its own test suite, and installs: |
706 | ||
707 | $ git clean -xdf | |
a42352ee DM |
708 | $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest |
709 | ||
710 | # or if it's an odd-numbered version: | |
a0db33fe | 711 | $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest |
a42352ee | 712 | |
a0db33fe DM |
713 | $ make test install |
714 | ||
52a66c2c DM |
715 | Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and |
716 | C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected, | |
a0db33fe | 717 | especially as regards version numbers, patch and/or RC levels, and @INC |
52a66c2c DM |
718 | paths. Note that as they have been been built from a git working |
719 | directory, they will still identify themselves using git tags and | |
01725c10 A |
720 | commits. (Note that for an odd-numbered version, perl will install |
721 | itself as C<perl5.x.y>). C<perl -v> will identify itself as: | |
722 | ||
78957677 | 723 | This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef)) |
01725c10 | 724 | |
78957677 | 725 | where 5.X.Z is the latest tag, NNN the number of commits since this tag, |
01725c10 | 726 | and C<< deadbeef >> commit of that tag. |
52a66c2c DM |
727 | |
728 | Then delete the temporary installation. | |
729 | ||
dc0a4df9 DM |
730 | |
731 | =head3 push the work so far | |
52a66c2c | 732 | |
a0db33fe DM |
733 | Push all your recent commits: |
734 | ||
04e228f7 | 735 | $ git push origin release-5.xx.yy |
96054f12 | 736 | |
dc0a4df9 | 737 | =head3 tag the release |
96054f12 | 738 | |
e8c01f92 | 739 | Tag the release (e.g.): |
96054f12 | 740 | |
b6d23947 | 741 | $ git tag v5.11.0 -m "First release of the v5.11 series!" |
e8c01f92 | 742 | |
6a958a95 | 743 | It is B<VERY> important that from this point forward, you not push |
f662f3b7 JV |
744 | your git changes to the Perl master repository. If anything goes |
745 | wrong before you publish your newly-created tag, you can delete | |
746 | and recreate it. Once you push your tag, we're stuck with it | |
747 | and you'll need to use a new version number for your release. | |
748 | ||
dc0a4df9 DM |
749 | |
750 | =head3 build the tarball | |
a0db33fe | 751 | |
0dcf3caa | 752 | Before you run the following, you might want to install 7-Zip (the |
0dcb816b | 753 | C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or |
0dcf3caa LB |
754 | the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian, |
755 | or the C<advancecomp> port on macports - 7-Zip on Windows is the | |
756 | same code as AdvanceCOMP, so Windows users get the smallest files | |
757 | first time). These compress about 5% smaller than gzip and bzip2. | |
758 | Over the lifetime of your distribution this will save a lot of | |
759 | people a small amount of download time and disk space, which adds | |
760 | up. | |
761 | ||
8c35d285 JV |
762 | Create a tarball. Use the C<-s> option to specify a suitable suffix for |
763 | the tarball and directory name: | |
764 | ||
765 | $ cd root/of/perl/tree | |
766 | $ make distclean | |
75a012fe DM |
767 | $ git clean -xdf # make sure perl and git agree on files |
768 | $ git status # and there's nothing lying around | |
8c35d285 | 769 | |
8c35d285 JV |
770 | $ perl Porting/makerel -b -s RC1 # for a release candidate |
771 | $ perl Porting/makerel -b # for a final release | |
772 | ||
773 | This creates the directory F<../perl-x.y.z-RC1> or similar, copies all | |
774 | the MANIFEST files into it, sets the correct permissions on them, | |
775 | adds DOS line endings to some, then tars it up as | |
776 | F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C<tar.bz2> file. | |
777 | ||
6480287f MT |
778 | If you're getting your tarball suffixed with -uncommitted and you're sure |
779 | your changes were all committed, you can override the suffix with: | |
780 | ||
781 | $ perl Porting/makerel -b -s '' | |
96054f12 | 782 | |
8c35d285 JV |
783 | XXX if we go for extra tags and branches stuff, then add the extra details |
784 | here | |
785 | ||
dc0a4df9 | 786 | Finally, clean up the temporary directory, e.g. |
a42352ee DM |
787 | |
788 | $ rm -rf ../perl-x.y.z-RC1 | |
789 | ||
dc0a4df9 DM |
790 | |
791 | =head3 test the tarball | |
792 | ||
00c28750 | 793 | Once you have a tarball it's time to test the tarball (not the repository). |
dc0a4df9 | 794 | |
00c28750 | 795 | =head4 Copy the tarball to a web server |
a42352ee | 796 | |
8c35d285 JV |
797 | Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you |
798 | have access to. | |
799 | ||
00c28750 | 800 | =head4 Download the tarball to another machine |
8c35d285 JV |
801 | |
802 | Download the tarball to some other machine. For a release candidate, | |
803 | you really want to test your tarball on two or more different platforms | |
804 | and architectures. The #p5p IRC channel on irc.perl.org is a good place | |
805 | to find willing victims. | |
806 | ||
00c28750 | 807 | =head4 Check that F<Configure> works |
8c35d285 JV |
808 | |
809 | Check that basic configuration and tests work on each test machine: | |
810 | ||
811 | $ ./Configure -des && make all test | |
f6af4394 | 812 | |
00c28750 | 813 | =head4 Run the test harness and install |
f6af4394 | 814 | |
8c35d285 JV |
815 | Check that the test harness and install work on each test machine: |
816 | ||
a42352ee | 817 | $ make distclean |
8c35d285 | 818 | $ ./Configure -des -Dprefix=/install/path && make all test_harness install |
a42352ee | 819 | $ cd /install/path |
8c35d285 | 820 | |
00c28750 | 821 | =head4 Check C<perl -v> and C<perl -V> |
8c35d285 JV |
822 | |
823 | Check that the output of C<perl -v> and C<perl -V> are as expected, | |
824 | especially as regards version numbers, patch and/or RC levels, and @INC | |
825 | paths. | |
826 | ||
827 | Note that the results may be different without a F<.git/> directory, | |
828 | which is why you should test from the tarball. | |
829 | ||
00c28750 | 830 | =head4 Run the Installation Verification Procedure utility |
459fc3ca | 831 | |
9651cacc | 832 | $ ./perl utils/perlivp |
459fc3ca DM |
833 | ... |
834 | All tests successful. | |
835 | $ | |
836 | ||
00c28750 | 837 | =head4 Compare the installed paths to the last release |
459fc3ca | 838 | |
d60a1044 DM |
839 | Compare the pathnames of all installed files with those of the previous |
840 | release (i.e. against the last installed tarball on this branch which you | |
841 | have previously verified using this same procedure). In particular, look | |
842 | for files in the wrong place, or files no longer included which should be. | |
843 | For example, suppose the about-to-be-released version is 5.10.1 and the | |
844 | previous is 5.10.0: | |
845 | ||
846 | cd installdir-5.10.0/ | |
847 | find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1 | |
848 | cd installdir-5.10.1/ | |
849 | find . -type f | sort > /tmp/f2 | |
850 | diff -u /tmp/f[12] | |
851 | ||
29205e9c | 852 | =head4 Bootstrap the CPAN client |
d60a1044 | 853 | |
8c35d285 JV |
854 | Bootstrap the CPAN client on the clean install: |
855 | ||
29205e9c | 856 | $ bin/cpan |
8c35d285 | 857 | |
29205e9c | 858 | =head4 Install the Inline module with CPAN and test it |
8c35d285 | 859 | |
a42352ee DM |
860 | Try installing a popular CPAN module that's reasonably complex and that |
861 | has dependencies; for example: | |
8c35d285 | 862 | |
a42352ee DM |
863 | CPAN> install Inline |
864 | CPAN> quit | |
8c35d285 JV |
865 | |
866 | Check that your perl can run this: | |
867 | ||
16c60e4e | 868 | $ bin/perl -lwe "use Inline C => q[int f() { return 42;}]; print f" |
a42352ee DM |
869 | 42 |
870 | $ | |
8c35d285 | 871 | |
00c28750 | 872 | =head4 Bootstrap the CPANPLUS client |
8c35d285 JV |
873 | |
874 | Bootstrap the CPANPLUS client on the clean install: | |
875 | ||
75a012fe | 876 | $ bin/cpanp |
8c35d285 | 877 | |
00c28750 | 878 | =head4 Install the DBI module with CPANPLUS |
8c35d285 | 879 | |
a42352ee DM |
880 | CPAN Terminal> i DBI |
881 | CPAN Terminal> quit | |
882 | $ bin/perl -MDBI -e 1 | |
75a012fe | 883 | $ |
8c35d285 | 884 | |
00c28750 | 885 | =head4 Make sure that perlbug works |
8c35d285 | 886 | |
00c28750 | 887 | Test L<perlbug> with the following: |
47b1f096 | 888 | |
a14438df | 889 | $ bin/perlbug |
47b1f096 DM |
890 | ... |
891 | Subject: test bug report | |
892 | Local perl administrator [yourself]: | |
893 | Editor [vi]: | |
894 | Module: | |
895 | Category [core]: | |
896 | Severity [low]: | |
897 | (edit report) | |
898 | Action (Send/Display/Edit/Subject/Save to File): f | |
899 | Name of file to save message in [perlbug.rep]: | |
900 | Action (Send/Display/Edit/Subject/Save to File): q | |
901 | ||
902 | and carefully examine the output (in F<perlbug.rep]>), especially | |
903 | the "Locally applied patches" section. If everything appears okay, then | |
75a012fe DM |
904 | delete the file, and try it again, this time actually submitting the bug |
905 | report. Check that it shows up, then remember to close it! | |
47b1f096 | 906 | |
da571fa1 | 907 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
908 | |
909 | =head3 monitor smokes | |
47b1f096 | 910 | |
f6af4394 DM |
911 | Wait for the smoke tests to catch up with the commit which this release is |
912 | based on (or at least the last commit of any consequence). | |
7277a900 | 913 | |
f6af4394 DM |
914 | Then check that the smoke tests pass (particularly on Win32). If not, go |
915 | back and fix things. | |
7277a900 | 916 | |
6a958a95 | 917 | Note that for I<BLEAD-POINT> releases this may not be practical. It takes a |
1eefd7d5 | 918 | long time for the smokers to catch up, especially the Win32 |
6a958a95 DM |
919 | smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL> |
920 | releases, but for I<BLEAD-POINT> releases sometimes the best you can do is | |
921 | to plead with people on IRC to test stuff on their platforms, fire away, | |
922 | and then hope for the best. | |
7277a900 | 923 | |
dc0a4df9 DM |
924 | |
925 | =head3 upload to PAUSE | |
7277a900 | 926 | |
f6af4394 | 927 | Once smoking is okay, upload it to PAUSE. This is the point of no return. |
db3f805e JV |
928 | If anything goes wrong after this point, you will need to re-prepare |
929 | a new release with a new minor version or RC number. | |
930 | ||
a14438df DM |
931 | https://pause.perl.org/ |
932 | ||
933 | (Login, then select 'Upload a file to CPAN') | |
934 | ||
45924287 RS |
935 | If your workstation is not connected to a high-bandwidth, |
936 | high-reliability connection to the Internet, you should probably use the | |
937 | "GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the | |
938 | new release from wherever you put it for testers to find it. This will | |
939 | eliminate anxious gnashing of teeth while you wait to see if your | |
940 | 15 megabyte HTTP upload successfully completes across your slow, twitchy | |
c27b4e97 SH |
941 | cable modem. You can make use of your home directory on dromedary for |
942 | this purpose: F<http://users.perl5.git.perl.org/~USERNAME> maps to | |
943 | F</home/USERNAME/public_html>, where F<USERNAME> is your login account | |
944 | on dromedary. I<Remember>: if your upload is partially successful, you | |
945 | may need to contact a PAUSE administrator or even bump the version of perl. | |
45924287 | 946 | |
a42352ee | 947 | Upload both the .gz and .bz2 versions of the tarball. |
f6af4394 | 948 | |
38195a8c DG |
949 | Do not proceed any further until you are sure that your tarballs are on |
950 | CPAN. Check your authors directory on one of the "fast" CPAN mirrors | |
b28f69c2 | 951 | (e.g., cpan.hexten.net |
38195a8c | 952 | or cpan.cpantesters.org) to confirm that your uploads have been successful. |
c27b4e97 | 953 | |
00c28750 DR |
954 | =for checklist skip RC |
955 | ||
956 | =head3 wait for indexing | |
957 | ||
76526317 FR |
958 | I<You MUST SKIP this step for RC> |
959 | ||
960 | Wait until you receive notification emails from the PAUSE indexer | |
961 | confirming that your uploads have been received. IMPORTANT -- you will | |
962 | probably get an email that indexing has failed, due to module permissions. | |
963 | This is considered normal. | |
964 | ||
dc0a4df9 DM |
965 | |
966 | =head3 publish tag | |
210de33e | 967 | |
f662f3b7 | 968 | Now that you've shipped the new perl release to PAUSE, it's |
e8c01f92 | 969 | time to publish the tag you created earlier to the public git repo (e.g.): |
f662f3b7 JV |
970 | |
971 | $ git push origin tag v5.11.0 | |
f6af4394 | 972 | |
da571fa1 | 973 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
974 | |
975 | =head3 disarm patchlevel.h | |
f6af4394 | 976 | |
6a958a95 | 977 | I<You MUST SKIP this step for BLEAD-POINT release> |
113f3f4c | 978 | |
a42352ee | 979 | Disarm the F<patchlevel.h> change; for example, |
d7eb1120 DM |
980 | |
981 | static const char * const local_patches[] = { | |
982 | NULL | |
983 | - ,"RC1" | |
984 | PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ | |
985 | ||
986 | Be sure to commit your change: | |
987 | ||
988 | $ git commit -m 'disarm RCnnn bump' patchlevel.h | |
a14438df | 989 | $ git push origin .... |
d7eb1120 | 990 | |
2e831dfd | 991 | |
dc0a4df9 DM |
992 | |
993 | =head3 announce to p5p | |
2e831dfd | 994 | |
db3f805e | 995 | Mail p5p to announce your new release, with a quote you prepared earlier. |
f6af4394 | 996 | |
098d30ef | 997 | Use the template at Porting/release_announcement_template.txt |
dc0a4df9 | 998 | |
a8cecd9d RS |
999 | Send a carbon copy to C<noc@metacpan.org> |
1000 | ||
ff721450 JL |
1001 | =head3 merge release branch back to blead |
1002 | ||
1003 | If you made a release branch for this release, merge it back into master now, | |
1004 | and delete it. | |
1005 | ||
1006 | git checkout blead | |
1007 | git pull | |
1008 | git merge release-5.xx.yy | |
1009 | git push | |
1010 | git push origin :release-5.xx.yy | |
1011 | git branch -d release-5.xx.yy | |
1012 | ||
dc0a4df9 | 1013 | =head3 update epigraphs.pod |
f6af4394 | 1014 | |
85531b0a | 1015 | Add your quote to F<Porting/epigraphs.pod> and commit it. |
606d51b7 Z |
1016 | Your release announcement will probably not have reached the web-visible |
1017 | archives yet, so you won't be able to include the customary link to the | |
1018 | release announcement yet. | |
dc0a4df9 | 1019 | |
b02b3ec7 DR |
1020 | =head3 blog about your epigraph |
1021 | ||
1022 | If you have a blog, please consider writing an entry in your blog explaining | |
1023 | why you chose that particular quote for your epigraph. | |
1024 | ||
da571fa1 DR |
1025 | =for checklist skip RC |
1026 | ||
dc0a4df9 | 1027 | =head3 Module::CoreList nagging |
85531b0a | 1028 | |
bc4c40f2 | 1029 | I<You MUST SKIP this step for RC> |
8c35d285 | 1030 | |
75a012fe DM |
1031 | Remind the current maintainer of C<Module::CoreList> to push a new release |
1032 | to CPAN. | |
7277a900 | 1033 | |
da571fa1 | 1034 | =for checklist skip RC |
dc0a4df9 DM |
1035 | |
1036 | =head3 new perldelta | |
a2cba4bc | 1037 | |
bc4c40f2 | 1038 | I<You MUST SKIP this step for RC> |
7277a900 | 1039 | |
bcfe7366 | 1040 | Create a new perldelta. |
5ef3945b | 1041 | |
bcfe7366 | 1042 | =over 4 |
8e967a1c | 1043 | |
bcfe7366 | 1044 | =item * |
8e967a1c | 1045 | |
bcfe7366 | 1046 | Confirm that you have a clean checkout with no local changes. |
c5b87fed | 1047 | |
bcfe7366 | 1048 | =item * |
17163f85 | 1049 | |
bcfe7366 | 1050 | Run F<Porting/new-perldelta.pl> |
8e967a1c | 1051 | |
bcfe7366 | 1052 | =item * |
17163f85 | 1053 | |
bcfe7366 | 1054 | Run the C<git add> commands it outputs to add new and modified files. |
7277a900 | 1055 | |
bcfe7366 | 1056 | =item * |
7277a900 | 1057 | |
bcfe7366 | 1058 | Verify that the build still works, by running C<./Configure> and |
fd76d40d SH |
1059 | C<make test_porting>. (On Win32, run C<nmake> and |
1060 | C<nmake test TEST_FILES="porting\*.t ..\lib\diagnostics.t">.) | |
17163f85 | 1061 | |
bcfe7366 | 1062 | =item * |
17163f85 | 1063 | |
bcfe7366 NC |
1064 | If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>, |
1065 | run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail. | |
1066 | Skip to the end of its test output to see the options it offers you. | |
57433fbf | 1067 | |
bcfe7366 | 1068 | =item * |
75a012fe | 1069 | |
bcfe7366 | 1070 | When C<make test_porting> passes, commit the new perldelta. |
75a012fe | 1071 | |
bcfe7366 | 1072 | =back |
75a012fe | 1073 | |
21768cb3 | 1074 | At this point you may want to compare the commit with a previous bump to |
b6bac75d | 1075 | see if they look similar. See commit 4eabcf701b for an example of a |
75a012fe | 1076 | previous version bump. |
57433fbf | 1077 | |
30f926b5 | 1078 | =for checklist skip MAINT RC |
dc0a4df9 DM |
1079 | |
1080 | =head3 bump version | |
57433fbf | 1081 | |
30f926b5 | 1082 | I<You MUST SKIP this step for RC and MAINT> |
dc0a62a1 | 1083 | |
6a958a95 DM |
1084 | If this was a BLEAD-FINAL release (i.e. the first release of a new maint |
1085 | series, 5.x.0 where x is even), then bump the version in the blead branch | |
1086 | in git, e.g. 5.12.0 to 5.13.0. | |
17163f85 | 1087 | |
6d5e92cd FC |
1088 | First, add a new feature bundle to F<regen/feature.pl>, initially by just |
1089 | copying the exiting entry, and bump the file's $VERSION (after the __END__ | |
1090 | marker); e.g. | |
17163f85 DM |
1091 | |
1092 | "5.14" => [qw(switch say state unicode_strings)], | |
1093 | + "5.15" => [qw(switch say state unicode_strings)], | |
addebd58 | 1094 | |
57fef7cc FC |
1095 | Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>. |
1096 | ||
dc0a4df9 DM |
1097 | Then follow the section L<"Bump the version number"> to bump the version |
1098 | in the remaining files and test and commit. | |
17163f85 | 1099 | |
30f926b5 JL |
1100 | If this was a BLEAD-POINT release, then just follow the section |
1101 | L<"Bump the version number">. | |
1102 | ||
17163f85 | 1103 | |
d5c37431 NC |
1104 | =head3 clean build and test |
1105 | ||
1106 | Run a clean build and test to make sure nothing obvious is broken. | |
1107 | ||
1108 | In particular, F<Porting/perldelta_template.pod> is intentionally exempted | |
1109 | from podchecker tests, to avoid false positives about placeholder text. | |
1110 | However, once it's copied to F<pod/perldelta.pod> the contents can now | |
ef4474b5 KW |
1111 | cause test failures. Problems should resolved by doing one of the |
1112 | following: | |
1113 | ||
1114 | =over | |
1115 | ||
1116 | =item 1 | |
1117 | ||
1118 | Replace placeholder text with correct text. | |
1119 | ||
1120 | =item 2 | |
1121 | ||
1122 | If the problem is from a broken placeholder link, you can add it to the | |
1123 | array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines | |
1124 | containing such links should be marked with C<XXX> so that they get | |
1125 | cleaned up before the next release. | |
1126 | ||
1127 | =item 3 | |
1128 | ||
1129 | Following the instructions output by F<t/porting/podcheck.t> on how to | |
1130 | update its exceptions database. | |
1131 | ||
1132 | =back | |
d5c37431 | 1133 | |
dc0a4df9 DM |
1134 | =head3 push commits |
1135 | ||
1136 | Finally, push any commits done above. | |
1137 | ||
1138 | $ git push origin .... | |
1139 | ||
da571fa1 | 1140 | =for checklist skip BLEAD-POINT MAINT RC |
dc0a4df9 DM |
1141 | |
1142 | =head3 create maint branch | |
17163f85 | 1143 | |
6a958a95 | 1144 | I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT> |
17163f85 | 1145 | |
6a958a95 DM |
1146 | If this was a BLEAD-FINAL release (i.e. the first release of a new maint |
1147 | series, 5.x.0 where x is even), then create a new maint branch based on | |
1148 | the commit tagged as the current release. | |
7277a900 | 1149 | |
233ca920 JV |
1150 | Assuming you're using git 1.7.x or newer: |
1151 | ||
17163f85 | 1152 | $ git checkout -b maint-5.12 v5.12.0 |
233ca920 | 1153 | $ git push origin -u maint-5.12 |
addebd58 | 1154 | |
dc0a4df9 | 1155 | |
da571fa1 DR |
1156 | =for checklist skip BLEAD-POINT MAINT RC |
1157 | ||
d5722260 DK |
1158 | =head3 make the maint branch available in the APC |
1159 | ||
1160 | Clone the new branch into /srv/gitcommon/branches on camel so the APC will | |
1161 | receive its changes. | |
1162 | ||
07697565 | 1163 | $ git clone --branch maint-5.14 /gitroot/perl.git \ |
d5722260 | 1164 | ? /srv/gitcommon/branches/perl-5.14.x |
07697565 | 1165 | $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x |
d5722260 DK |
1166 | |
1167 | And nag the sysadmins to make this directory available via rsync. | |
1168 | ||
da571fa1 | 1169 | =for checklist skip BLEAD-POINT RC |
d5722260 | 1170 | |
dc0a4df9 | 1171 | =head3 copy perldelta.pod to other branches |
addebd58 | 1172 | |
6a958a95 | 1173 | I<You MUST SKIP this step for RC, BLEAD-POINT> |
8c35d285 | 1174 | |
c5b87fed | 1175 | Copy the perldelta.pod for this release into the other branches; for |
75a012fe | 1176 | example: |
7277a900 | 1177 | |
c5b87fed | 1178 | $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example |
75a012fe DM |
1179 | $ git add pod/perl5101delta.pod |
1180 | ||
0aef0fe5 | 1181 | Edit F<pod/perl.pod> to add an entry for the file, e.g.: |
75a012fe DM |
1182 | |
1183 | perl5101delta Perl changes in version 5.10.1 | |
bc4c40f2 | 1184 | |
75a012fe | 1185 | Then rebuild various files: |
7277a900 | 1186 | |
00b85c8d | 1187 | $ perl Porting/pod_rules.pl |
75a012fe DM |
1188 | |
1189 | Finally, commit: | |
1190 | ||
1191 | $ git commit -a -m 'add perlXXXdelta' | |
7277a900 | 1192 | |
dc0a4df9 DM |
1193 | |
1194 | =head3 update perlhist.pod in other branches | |
7277a900 | 1195 | |
f6af4394 | 1196 | Make sure any recent F<pod/perlhist.pod> entries are copied to |
e8a7a70e | 1197 | F<perlhist.pod> on other branches |
f6af4394 | 1198 | e.g. |
7277a900 | 1199 | |
f6af4394 | 1200 | 5.8.9 2008-Dec-14 |
7277a900 | 1201 | |
dc0a4df9 DM |
1202 | |
1203 | =head3 bump RT version number | |
6e40fbf9 | 1204 | |
7c139051 DR |
1205 | Log into http://rt.perl.org/ and check whether the new version is in the RT |
1206 | fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is | |
1207 | to go to L<https://rt.perl.org/rt3/Search/Build.html> and click on the drop | |
1208 | downs next to the C<Perl Version> and C<Fixed In> labels. | |
1209 | ||
1210 | If the new version is not listed there, send an email to C<perlbug-admin at | |
1211 | perl.org> requesting this. | |
dc0a4df9 DM |
1212 | |
1213 | =head3 Relax! | |
a3738a12 | 1214 | |
bc4c40f2 JV |
1215 | I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some |
1216 | much-needed rest and relaxation>. | |
8c35d285 JV |
1217 | |
1218 | Thanks for releasing perl! | |
1219 | ||
7277a900 | 1220 | |
b28f69c2 Z |
1221 | =head2 Building a release - the day after |
1222 | ||
606d51b7 Z |
1223 | =head3 link announcement in epigraphs.pod |
1224 | ||
1225 | Add, to your quote to F<Porting/epigraphs.pod>, a link to the release | |
1226 | announcement in the web-visible mailing list archive. Commit it. | |
1227 | ||
dc0a4df9 DM |
1228 | =head3 check tarball availability |
1229 | ||
1230 | Check various website entries to make sure the that tarball has appeared | |
1231 | and is properly indexed: | |
1232 | ||
b28f69c2 Z |
1233 | =over 4 |
1234 | ||
1235 | =item * | |
1236 | ||
98df743a Z |
1237 | Check your author directory under L<http://www.cpan.org/authors/id/> |
1238 | to ensure that the tarballs are available on the website. | |
b28f69c2 Z |
1239 | |
1240 | =item * | |
1241 | ||
98df743a Z |
1242 | Check C</src> on CPAN (on a fast mirror) to ensure that links to |
1243 | the new tarballs have appeared. There should be links in C</src/5.0> | |
02e2c3c0 SH |
1244 | (which is accumulating all new versions), and an appropriate mention in |
1245 | C</src> (which describes the latest versions in each branch, with links). | |
98df743a Z |
1246 | |
1247 | These links should appear automatically, some hours after upload. | |
02e2c3c0 | 1248 | If they don't, or the C</src> description is inadequate, |
98df743a | 1249 | ask Ask <ask@perl.org>. |
b28f69c2 Z |
1250 | |
1251 | =item * | |
1252 | ||
98df743a Z |
1253 | Check L<http://www.cpan.org/src/> to ensure that the C</src> updates |
1254 | have been correctly mirrored to the website. | |
1255 | If they haven't, ask Ask <ask@perl.org>. | |
1256 | ||
1257 | =item * | |
b28f69c2 | 1258 | |
98df743a Z |
1259 | Check L<http://search.cpan.org> to see if it has indexed the distribution. |
1260 | It should be visible at a URL like C<http://search.cpan.org/dist/perl-5.10.1/>. | |
b28f69c2 | 1261 | |
dc0a4df9 | 1262 | =back |
b28f69c2 | 1263 | |
e7b51df1 | 1264 | =for checklist skip RC |
dc0a4df9 DM |
1265 | |
1266 | =head3 update dev.perl.org | |
1267 | ||
e7b51df1 | 1268 | I<You MUST SKIP this step for a RC release> |
98df743a | 1269 | |
5fbaa27a | 1270 | In your C<perlweb> repository, link to the new release. For a new |
7a664ed5 RS |
1271 | latest-maint release, edit F<docs/shared/tpl/stats.html>. Otherwise, |
1272 | edit F<docs/dev/perl5/index.html>. | |
1273 | ||
1274 | Then make a pull request to Leo Lapworth. If this fails for some reason | |
1275 | and you cannot cajole anybody else into submitting that change, you can | |
1276 | mail Leo as last resort. | |
b28f69c2 | 1277 | |
7dbb22ac A |
1278 | This repository can be found on L<github|https://github.com/perlorg/perlweb>. |
1279 | ||
da571fa1 | 1280 | =for checklist end |
b28f69c2 | 1281 | |
7277a900 GS |
1282 | =head1 SOURCE |
1283 | ||
f6af4394 DM |
1284 | Based on |
1285 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html, | |
1286 | plus a whole bunch of other sources, including private correspondence. | |
7277a900 GS |
1287 | |
1288 | =cut | |
1289 |