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 | ||
a88465cf KW |
18 | perl Porting/make-rmg-checklist \ |
19 | --version [5.x.y-RC#] > /tmp/rmg.pod | |
0056d3d2 | 20 | |
ad1baa5f AC |
21 | You can also pass the C<--html> flag to generate an HTML document instead of |
22 | POD. | |
23 | ||
a88465cf KW |
24 | perl Porting/make-rmg-checklist --html \ |
25 | --version [5.x.y-RC#] > /tmp/rmg.html | |
ad1baa5f | 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 | |
5e770dfc RS |
33 | New releases of perl are made each month on the 20th by a release engineer |
34 | appointed by the Steering Council. The release engineer roster and schedule | |
35 | can be found in Porting/release_schedule.pod. | |
7277a900 | 36 | |
fdaa3f94 CBW |
37 | This document both helps as a check-list for the release engineer |
38 | and is a base for ideas on how the various tasks could be automated | |
8c35d285 | 39 | or distributed. |
7277a900 | 40 | |
da571fa1 | 41 | The checklist of a typical release cycle is as follows: |
f6af4394 | 42 | |
a88465cf | 43 | (5.10.1 is released, and post-release actions have been done) |
f6af4394 | 44 | |
a88465cf | 45 | ...time passes... |
f6af4394 | 46 | |
a88465cf KW |
47 | a few weeks before the release, a number of steps are performed, |
48 | including bumping the version to 5.10.2 | |
636a1918 | 49 | |
a88465cf | 50 | ...a few weeks pass... |
46743ef7 | 51 | |
a88465cf | 52 | perl-5.10.2-RC1 is released |
f6af4394 | 53 | |
a88465cf | 54 | perl-5.10.2 is released |
f6af4394 | 55 | |
a88465cf KW |
56 | post-release actions are performed, including creating new |
57 | perldelta.pod | |
f6af4394 | 58 | |
a88465cf | 59 | ... the cycle continues ... |
7277a900 GS |
60 | |
61 | =head1 DETAILS | |
62 | ||
6a958a95 DM |
63 | Some of the tasks described below apply to all four types of |
64 | release of Perl. (blead, RC, final release of maint, final | |
8c35d285 | 65 | release of blead). Some of these tasks apply only to a subset |
fdaa3f94 | 66 | of these release types. If a step does not apply to a given |
8c35d285 JV |
67 | type of release, you will see a notation to that effect at |
68 | the beginning of the step. | |
69 | ||
70 | =head2 Release types | |
71 | ||
72 | =over 4 | |
73 | ||
8c35d285 JV |
74 | =item Release Candidate (RC) |
75 | ||
d60a1044 DM |
76 | A release candidate is an attempt to produce a tarball that is a close as |
77 | possible to the final release. Indeed, unless critical faults are found | |
78 | during the RC testing, the final release will be identical to the RC | |
79 | barring a few minor fixups (updating the release date in F<perlhist.pod>, | |
80 | removing the RC status from F<patchlevel.h>, etc). If faults are found, | |
81 | then the fixes should be put into a new release candidate, never directly | |
82 | into a final release. | |
8c35d285 | 83 | |
6a958a95 DM |
84 | |
85 | =item Stable/Maint release (MAINT). | |
86 | ||
87 | A release with an even version number, and subversion number > 0, such as | |
88 | 5.14.1 or 5.14.2. | |
8c35d285 JV |
89 | |
90 | At this point you should have a working release candidate with few or no | |
91 | changes since. | |
92 | ||
93 | It's essentially the same procedure as for making a release candidate, but | |
94 | with a whole bunch of extra post-release steps. | |
95 | ||
74648505 DM |
96 | Note that for a maint release there are two versions of this guide to |
97 | consider: the one in the maint branch, and the one in blead. Which one to | |
98 | use is a fine judgement. The blead one will be most up-to-date, while | |
99 | it might describe some steps or new tools that aren't applicable to older | |
100 | maint branches. It is probably best to review both versions of this | |
101 | document, but to most closely follow the steps in the maint version. | |
102 | ||
6a958a95 DM |
103 | =item A blead point release (BLEAD-POINT) |
104 | ||
105 | A release with an odd version number, such as 5.15.0 or 5.15.1. | |
106 | ||
107 | This isn't for production, so it has less stability requirements than for | |
108 | other release types, and isn't preceded by RC releases. Other than that, | |
109 | it is similar to a MAINT release. | |
110 | ||
111 | =item Blead final release (BLEAD-FINAL) | |
112 | ||
113 | A release with an even version number, and subversion number == 0, such as | |
dc0a4df9 | 114 | 5.14.0. That is to say, it's the big new release once per year. |
8c35d285 JV |
115 | |
116 | It's essentially the same procedure as for making a release candidate, but | |
6a958a95 | 117 | with a whole bunch of extra post-release steps, even more than for MAINT. |
8c35d285 JV |
118 | |
119 | =back | |
7277a900 | 120 | |
da571fa1 | 121 | =for checklist begin |
dc0a4df9 | 122 | |
fd838dcf JV |
123 | =head2 Prerequisites |
124 | ||
125 | Before you can make an official release of perl, there are a few | |
126 | hoops you need to jump through: | |
127 | ||
00c28750 | 128 | =head3 PAUSE account with pumpkin status |
8c35d285 | 129 | |
fd838dcf JV |
130 | Make sure you have a PAUSE account suitable for uploading a perl release. |
131 | If you don't have a PAUSE account, then request one: | |
132 | ||
a88465cf | 133 | https://pause.perl.org/pause/query?ACTION=request_id |
fd838dcf | 134 | |
9a3b7d40 FR |
135 | Check that your account is allowed to upload perl distros: go to |
136 | L<https://pause.perl.org/pause/authenquery?ACTION=who_pumpkin> and check that | |
137 | your PAUSE ID is listed there. If not, ask Andreas KE<0xf6>nig to add your ID | |
138 | to the list of people allowed to upload something called perl. You can find | |
139 | Andreas' email address at: | |
4d2c8158 | 140 | |
a88465cf | 141 | https://pause.perl.org/pause/query?ACTION=pause_04imprint |
fd838dcf | 142 | |
ea207adc | 143 | =head3 GitHub access |
fd838dcf JV |
144 | |
145 | You will need a working C<git> installation, checkout of the perl | |
146 | git repository and perl commit bit. For information about working | |
4bfd0c50 | 147 | with perl and git, see L<perlgit>. |
fd838dcf JV |
148 | |
149 | If you are not yet a perl committer, you won't be able to make a | |
ea207adc | 150 | release. You will need to have a GitHub account (if you don't have one) |
5e770dfc RS |
151 | and contact the Steering Council with your username to get membership in the |
152 | L<< Perl-Releasers|https://github.com/orgs/Perl/teams/perl-releasers >> team. | |
fd838dcf | 153 | |
96644a2c DG |
154 | =head3 web-based file share |
155 | ||
156 | You will need to be able to share tarballs with #p5p members for | |
157 | pre-release testing, and you may wish to upload to PAUSE via URL. | |
158 | Make sure you have a way of sharing files, such as a web server or | |
159 | file-sharing service. | |
160 | ||
96644a2c DG |
161 | If you use Dropbox, you can append "raw=1" as a parameter to their usual |
162 | sharing link to allow direct download (albeit with redirects). | |
163 | ||
da571fa1 | 164 | =head3 Quotation for release announcement epigraph |
f6af4394 | 165 | |
dffcb1c0 | 166 | You will need a quotation to use as an epigraph to your release announcement. |
6939dacb | 167 | It will live forever (along with Perl), so make it a good one. |
46743ef7 | 168 | |
c282dc5e A |
169 | =head3 Install the previous version of perl |
170 | ||
171 | During the testing phase of the release you have created, you will be | |
172 | asked to compare the installed files with a previous install. Save yourself | |
173 | some time on release day, and have a (clean) install of the previous | |
174 | version ready. | |
175 | ||
5124a906 RL |
176 | =head3 Email account subscribed to perl5-porters |
177 | ||
178 | In order for your release announcement email to be delivered to the | |
179 | perl5-porters distribution list, the email address that you intend to | |
180 | send from must be subscribed to the list. | |
181 | ||
182 | Instructions for subscribing can be found here: | |
183 | L<List: perl5-porters|https://lists.perl.org/list/perl5-porters.html> | |
184 | ||
2e831dfd | 185 | =head2 Building a release - advance actions |
8c35d285 | 186 | |
9c39c536 A |
187 | The work of building a release candidate for an even numbered release |
188 | (BLEAD-FINAL) of perl generally starts several weeks before the first | |
189 | release candidate. Some of the following steps should be done regularly, | |
190 | but all I<must> be done in the run up to a release. | |
7277a900 | 191 | |
dc0a4df9 | 192 | =head3 dual-life CPAN module synchronisation |
f6af4394 | 193 | |
1d84c074 | 194 | To see which core distro versions differ from the current CPAN versions: |
f6af4394 | 195 | |
a88465cf | 196 | $ ./perl -Ilib Porting/core-cpan-diff -x -a |
7277a900 | 197 | |
1dbf7599 DG |
198 | However, this only checks whether the version recorded in |
199 | F<Porting/Maintainers.pl> differs from the latest on CPAN. It doesn't tell you | |
200 | if the code itself has diverged from CPAN. | |
7277a900 | 201 | |
1d84c074 JL |
202 | You can also run an actual diff of the contents of the modules, comparing core |
203 | to CPAN, to ensure that there were no erroneous/extraneous changes that need to | |
204 | be dealt with. You do this by not passing the C<-x> option: | |
7277a900 | 205 | |
a88465cf | 206 | $ ./perl -Ilib Porting/core-cpan-diff -a -o ~/corediffs |
1d84c074 | 207 | |
3804a1f7 SH |
208 | Passing C<-u cpan> will probably be helpful, since it limits the search to |
209 | distributions with 'cpan' upstream source. (It's OK for blead upstream to | |
210 | differ from CPAN because those dual-life releases usually come I<after> perl | |
211 | is released.) | |
1dbf7599 DG |
212 | |
213 | See also the C<-d> and C<-v> options for more detail (and the C<-u> option as | |
214 | mentioned above). You'll probably want to use the C<-c cachedir> option to | |
215 | avoid repeated CPAN downloads and may want to use C<-m file:///mirror/path> if | |
216 | you made a local CPAN mirror. Note that a minicpan mirror won't actually work, | |
217 | but can provide a good first pass to quickly get a list of modules which | |
218 | definitely haven't changed, to avoid having to download absolutely everything. | |
219 | ||
193c036f SH |
220 | For a BLEAD-POINT or BLEAD-FINAL release with 'cpan' upstream, if a CPAN |
221 | release appears to be ahead of blead, then consider updating it (or asking the | |
222 | relevant porter to do so). (However, if this is a BLEAD-FINAL release or one of | |
223 | the last BLEAD-POINT releases before it and hence blead is in some kind of | |
224 | "code freeze" state (e.g. the sequence might be "contentious changes freeze", | |
225 | then "user-visible changes freeze" and finally "full code freeze") then any | |
226 | CPAN module updates must be subject to the same restrictions, so it may not be | |
227 | possible to update all modules until after the BLEAD-FINAL release.) If blead | |
228 | contains edits to a 'cpan' upstream module, this is naughty but sometimes | |
229 | unavoidable to keep blead tests passing. Make sure the affected file has a | |
230 | CUSTOMIZED entry in F<Porting/Maintainers.pl>. | |
7277a900 | 231 | |
6a958a95 | 232 | If you are making a MAINT release, run C<core-cpan-diff> on both blead and |
636a1918 DM |
233 | maint, then diff the two outputs. Compare this with what you expect, and if |
234 | necessary, fix things up. For example, you might think that both blead | |
235 | and maint are synchronised with a particular CPAN module, but one might | |
fdaa3f94 | 236 | have some extra changes. |
636a1918 | 237 | |
cada13e6 KE |
238 | In any case, any cpan-first distribution that is listed as having files |
239 | "Customized for blead" in the output of cpan-core-diff should have requests | |
240 | submitted to the maintainer(s) to make a cpan release to catch up with blead. | |
241 | ||
242 | Additionally, all files listed as "modified" but not "customized for blead" | |
243 | should have entries added under the C<CUSTOMIZED> key in | |
244 | F<Porting/Maintainers.pl>, as well as checksums updated via: | |
245 | ||
a88465cf | 246 | cd t; ../perl -I../lib porting/customized.t --regen |
cada13e6 | 247 | |
6939dacb | 248 | =head4 Sync CPAN modules with the corresponding cpanE<sol> distro |
9c39c536 | 249 | |
b58fbdf5 JK |
250 | In most cases, once a new version of a distribution shipped with core has been |
251 | uploaded to CPAN, the core version thereof can be synchronized automatically | |
252 | with the program F<Porting/sync-with-cpan>. (But see the comments at the | |
253 | beginning of that program. In particular, it has not yet been exercised on | |
254 | Windows as much as it has on Unix-like platforms.) | |
255 | ||
256 | If, however, F<Porting/sync-with-cpan> does not provide good results, follow | |
257 | the steps below. | |
258 | ||
9c39c536 A |
259 | =over 4 |
260 | ||
261 | =item * | |
262 | ||
263 | Fetch the most recent version from CPAN. | |
264 | ||
265 | =item * | |
266 | ||
267 | Unpack the retrieved tarball. Rename the old directory; rename the new | |
268 | directory to the original name. | |
269 | ||
270 | =item * | |
271 | ||
9e40a104 | 272 | Restore any F<.gitignore> file. This can be done by issuing |
02cbdfef | 273 | C<git checkout .gitignore> in the F<cpan/Distro> directory. |
9c39c536 A |
274 | |
275 | =item * | |
276 | ||
277 | Remove files we do not need. That is, remove any files that match the | |
812ce6dc | 278 | entries in C<@IGNORABLE> in F<Porting/Maintainers.pl>, and anything that |
9c39c536 A |
279 | matches the C<EXCLUDED> section of the distro's entry in the C<%Modules> |
280 | hash. | |
281 | ||
282 | =item * | |
283 | ||
284 | Restore any files mentioned in the C<CUSTOMIZED> section, using | |
285 | C<git checkout>. Make any new customizations if necessary. Also, | |
286 | restore any files that are mentioned in C<@IGNORE>, but were checked | |
c5fb089a | 287 | into the repository anyway. |
9c39c536 A |
288 | |
289 | =item * | |
290 | ||
291 | For any new files in the distro, determine whether they are needed. | |
0f5c5828 | 292 | If not, delete them, and list them in either C<EXCLUDED> or C<@IGNORABLE>. |
9c39c536 A |
293 | Otherwise, add them to C<MANIFEST>, and run C<git add> to add the files |
294 | to the repository. | |
295 | ||
296 | =item * | |
297 | ||
298 | For any files that are gone, remove them from C<MANIFEST>, and use | |
299 | C<git rm> to tell git the files will be gone. | |
300 | ||
301 | =item * | |
302 | ||
303 | If the C<MANIFEST> file was changed in any of the previous steps, run | |
304 | C<perl Porting/manisort --output MANIFEST.sort; mv MANIFEST.sort MANIFEST>. | |
305 | ||
306 | =item * | |
307 | ||
308 | For any files that have an execute bit set, either remove the execute | |
02cbdfef | 309 | bit, or edit F<Porting/exec-bit.txt> |
9c39c536 A |
310 | |
311 | =item * | |
312 | ||
0b7399e1 | 313 | Run C<make> (or C<nmake> on Windows), see if C<perl> compiles. |
9c39c536 A |
314 | |
315 | =item * | |
316 | ||
317 | Run the tests for the package. | |
318 | ||
319 | =item * | |
320 | ||
812ce6dc | 321 | Run the tests in F<t/porting> (C<make test_porting>). |
9c39c536 A |
322 | |
323 | =item * | |
324 | ||
02cbdfef | 325 | Update the C<DISTRIBUTION> entry in F<Porting/Maintainers.pl>. |
9c39c536 A |
326 | |
327 | =item * | |
328 | ||
329 | Run a full configure/build/test cycle. | |
330 | ||
331 | =item * | |
332 | ||
333 | If everything is ok, commit the changes. | |
334 | ||
335 | =back | |
336 | ||
337 | For entries with a non-simple C<FILES> section, or with a C<MAP>, you | |
338 | may have to take more steps than listed above. | |
339 | ||
6939dacb | 340 | =head3 Ensure dual-life CPAN module stability |
7277a900 | 341 | |
6939dacb | 342 | This comes down to: |
7277a900 | 343 | |
78a62309 | 344 | for each module that fails its regression tests on $current |
a88465cf KW |
345 | did it fail identically on $previous? |
346 | if yes, "SEP" (Somebody Else's Problem, but try to make sure a | |
347 | bug ticket is filed) | |
348 | else work out why it failed (a bisect is useful for this) | |
ed380305 | 349 | |
78a62309 | 350 | attempt to group failure causes |
ed380305 | 351 | |
78a62309 | 352 | for each failure cause |
a88465cf KW |
353 | is that a regression? |
354 | if yes, figure out how to fix it | |
355 | (more code? revert the code that broke it) | |
356 | else | |
357 | (presumably) it's relying on something un-or-under-documented | |
358 | should the existing behaviour stay? | |
359 | yes - goto "regression" | |
360 | no - note it in perldelta as a significant bugfix | |
361 | (also, try to inform the module's author) | |
1aff5354 | 362 | |
00c28750 | 363 | =head3 monitor smoke tests for failures |
7277a900 | 364 | |
5157df7a | 365 | Similarly, monitor the smoking of core tests, and try to fix. See |
f6521f7c | 366 | L<https://tux.nl/perl5/smoke/index.html>, L<https://perl5.test-smoke.org/> |
a66bda92 | 367 | and L<http://perl.develop-help.com> for a summary. See also |
f6521f7c | 368 | L<https://www.nntp.perl.org/group/perl.daily-build.reports/> which has |
5157df7a | 369 | the raw reports. |
7277a900 | 370 | |
636a1918 DM |
371 | Similarly, monitor the smoking of perl for compiler warnings, and try to |
372 | fix. | |
373 | ||
1ed58cc9 TH |
374 | Additionally both L<Travis CI|https://travis-ci.org/Perl/perl5> and |
375 | L<GitHub Actions|https://github.com/Perl/perl5/actions> smokers run | |
376 | automatically. | |
377 | ||
5c296d48 SH |
378 | =for checklist skip BLEAD-POINT |
379 | ||
380 | =head3 monitor CPAN testers for failures | |
381 | ||
382 | For any release except a BLEAD-POINT: Examine the relevant analysis report(s) | |
4b05bc8e KW |
383 | at L<http://analysis.cpantesters.org/beforemaintrelease> to see how the |
384 | impending release is performing compared to previous releases with | |
385 | regard to building and testing CPAN modules. | |
5c296d48 | 386 | |
2fc8e8ba RS |
387 | That page accepts a query parameter, C<pair> that takes a pair of |
388 | colon-delimited versions to use for comparison. For example: | |
389 | ||
4b05bc8e | 390 | L<http://analysis.cpantesters.org/beforemaintrelease?pair=5.20.2:5.22.0%20RC1> |
2fc8e8ba | 391 | |
00c28750 | 392 | =head3 update perldelta |
636a1918 | 393 | |
f6af4394 | 394 | Get perldelta in a mostly finished state. |
db3f805e | 395 | |
6939dacb | 396 | Read F<Porting/how_to_write_a_perldelta.pod>, and try to make sure that |
636a1918 DM |
397 | every section it lists is, if necessary, populated and complete. Copy |
398 | edit the whole document. | |
f6af4394 | 399 | |
1dbf7599 DG |
400 | You won't be able to automatically fill in the "Updated Modules" section until |
401 | after Module::CoreList is updated (as described below in | |
402 | L<"update Module::CoreList">). | |
f6af4394 | 403 | |
dc0a4df9 DM |
404 | =head3 Bump the version number |
405 | ||
30f926b5 | 406 | Do not do this yet for a BLEAD-POINT release! You will do this at the end of |
cada13e6 | 407 | the release process (after building the final tarball, tagging etc). |
30f926b5 | 408 | |
dc0a4df9 | 409 | Increase the version number (e.g. from 5.12.0 to 5.12.1). |
04dbb930 | 410 | |
30f926b5 | 411 | For a release candidate for a stable perl, this should happen a week or two |
04dbb930 DG |
412 | before the first release candidate to allow sufficient time for testing and |
413 | smoking with the target version built into the perl executable. For | |
c5fb089a | 414 | subsequent release candidates and the final release, it is not necessary to |
04dbb930 | 415 | bump the version further. |
f6af4394 | 416 | |
8b2227e6 | 417 | There is a tool to semi-automate this process: |
f6af4394 | 418 | |
a88465cf | 419 | $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1 |
f6af4394 | 420 | |
8b2227e6 LB |
421 | Remember that this tool is largely just grepping for '5.10.0' or whatever, |
422 | so it will generate false positives. Be careful not change text like | |
423 | "this was fixed in 5.10.0"! | |
ceb7f800 | 424 | |
8b2227e6 | 425 | Use git status and git diff to select changes you want to keep. |
ceb7f800 | 426 | |
f6af4394 DM |
427 | Be particularly careful with F<INSTALL>, which contains a mixture of |
428 | C<5.10.0>-type strings, some of which need bumping on every release, and | |
e03f126c | 429 | some of which need to be left unchanged. |
2f05d209 | 430 | See below in L<"update INSTALL"> for more details. |
e03f126c | 431 | |
cdf175f7 SH |
432 | For the first RC release leading up to a BLEAD-FINAL release, update the |
433 | description of which releases are now "officially" supported in | |
434 | F<pod/perlpolicy.pod>. | |
435 | ||
6a958a95 DM |
436 | When doing a BLEAD-POINT or BLEAD-FINAL release, also make sure the |
437 | C<PERL_API_*> constants in F<patchlevel.h> are in sync with the version | |
ac2aec01 | 438 | you're releasing, unless you're absolutely sure the release you're about to |
df369d8e | 439 | make is 100% binary compatible to an earlier release. Note: for BLEAD-POINT |
fcd4ea8f SH |
440 | releases the bump should have already occurred at the end of the previous |
441 | release and this is something you would have to do at the very end. | |
df369d8e N |
442 | When releasing a MAINT perl version, the C<PERL_API_*> constants C<MUST NOT> |
443 | be changed as we aim to guarantee binary compatibility in maint branches. | |
45ce9531 | 444 | |
17163f85 DM |
445 | After editing, regenerate uconfig.h (this must be run on a system with a |
446 | /bin/sh available): | |
22be9667 | 447 | |
f185f654 | 448 | $ perl regen/uconfig_h.pl |
22be9667 | 449 | |
78957677 JL |
450 | This might not cause any new changes. |
451 | ||
82ce0493 A |
452 | You may also need to regen opcodes: |
453 | ||
f185f654 | 454 | $ ./perl -Ilib regen/opcode.pl |
82ce0493 | 455 | |
22be9667 JV |
456 | Test your changes: |
457 | ||
f185f654 KW |
458 | $ git clean -xdf # careful if you don't have local files to keep! |
459 | $ ./Configure -des -Dusedevel | |
460 | $ make | |
461 | $ make test | |
22be9667 | 462 | |
2c1c14b5 A |
463 | Do note that at this stage, porting tests will fail. They will continue |
464 | to fail until you've updated Module::CoreList, as described below. | |
465 | ||
54356a6f JV |
466 | Commit your changes: |
467 | ||
f185f654 KW |
468 | $ git status |
469 | $ git diff | |
470 | B<review the delta carefully> | |
54356a6f | 471 | |
f185f654 | 472 | $ git commit -a -m 'Bump the perl version in various places for 5.x.y' |
dc0a62a1 | 473 | |
21768cb3 | 474 | At this point you may want to compare the commit with a previous bump to |
ac2aec01 | 475 | see if they look similar. See commit f7cf42bb69 for an example of a |
21768cb3 FC |
476 | previous version bump. |
477 | ||
dc0a4df9 DM |
478 | When the version number is bumped, you should also update Module::CoreList |
479 | (as described below in L<"update Module::CoreList">) to reflect the new | |
81fc59ef DG |
480 | version number. |
481 | ||
dc0a4df9 | 482 | =head3 update INSTALL |
dc0a62a1 | 483 | |
2f05d209 | 484 | Review and update INSTALL to account for the change in version number. |
df369d8e | 485 | INSTALL for a BLEAD-POINT release should already contain the expected version. |
2f05d209 SH |
486 | The lines in F<INSTALL> about "is not binary compatible with" may require a |
487 | correct choice of earlier version to declare incompatibility with. These are | |
488 | in the "Changes and Incompatibilities" and "Coexistence with earlier versions | |
489 | of perl 5" sections. | |
dc0a62a1 | 490 | |
6a958a95 DM |
491 | Be particularly careful with the section "Upgrading from 5.X.Y or earlier". |
492 | The "X.Y" needs to be changed to the most recent version that we are | |
493 | I<not> binary compatible with. | |
494 | ||
495 | For MAINT and BLEAD-FINAL releases, this needs to refer to the last | |
496 | release in the previous development cycle (so for example, for a 5.14.x | |
497 | release, this would be 5.13.11). | |
498 | ||
499 | For BLEAD-POINT releases, it needs to refer to the previous BLEAD-POINT | |
96644a2c DG |
500 | release (so for 5.15.3 this would be 5.15.2). If the last release manager |
501 | followed instructions, this should have already been done after the last | |
502 | blead release, so you may find nothing to do here. | |
6a958a95 | 503 | |
74ecc54f N |
504 | =head3 update AUTHORS |
505 | ||
6ddd77ce | 506 | The AUTHORS file can be updated by running F<Porting/updateAUTHORS.pl>. |
74ecc54f | 507 | |
dc36bc82 | 508 | (The old method was C<Porting/checkAUTHORS.pl --update --from=5.X.Y> and |
6ddd77ce JK |
509 | it's still used under the hood, but you should use the |
510 | F<Porting/updateAUTHORS.pl> update.) | |
74ecc54f | 511 | |
dc36bc82 S |
512 | In the old method, for MAINT and BLEAD-FINAL releases, C<v5.X.Y> needs to |
513 | refer to the last release in the previous development cycle (so for | |
514 | example, for a 5.14.x release, this would be 5.13.11). | |
74ecc54f | 515 | |
dc36bc82 S |
516 | In the old method, for BLEAD-POINT releases, it needs to refer to the |
517 | previous BLEAD-POINT release (so for 5.15.3 this would be 5.15.2). | |
74ecc54f | 518 | |
2c81b405 | 519 | Note: It should not be harmful to use a wider range. |
74ecc54f | 520 | |
2c81b405 | 521 | Note: If you have uncommitted changes this could cause some warnings, |
31cd1f1d | 522 | and you might like to use the additional argument C<--to=upstream/blead> |
74ecc54f N |
523 | to use the last known git commit by GitHub. |
524 | ||
2c81b405 SH |
525 | Review the changes to the AUTHORS file, be sure you are not adding duplicate |
526 | entries or removing any entries, then commit your changes. | |
74ecc54f | 527 | |
a88465cf | 528 | $ git commit -a AUTHORS -m 'Update AUTHORS list for 5.x.y' |
74ecc54f | 529 | |
52d097d9 S |
530 | =head3 Check copyright years |
531 | ||
532 | Check that the copyright years are up to date by running: | |
533 | ||
a88465cf | 534 | $ pushd t; ../perl -I../lib porting/copyright.t --now |
52d097d9 S |
535 | |
536 | Remedy any test failures by editing README or perl.c accordingly (search for | |
537 | the "Copyright"). If updating perl.c, check if the file's own copyright date in | |
538 | the C comment at the top needs updating, as well as the one printed by C<-v>. | |
539 | ||
dc0a4df9 | 540 | =head3 Check more build configurations |
b82efa27 | 541 | |
d8fc5aa0 DR |
542 | Try running the full test suite against multiple Perl configurations. Here are |
543 | some sets of Configure flags you can try: | |
52a66c2c | 544 | |
d8fc5aa0 | 545 | =over 4 |
7277a900 | 546 | |
d8fc5aa0 DR |
547 | =item * |
548 | ||
549 | C<-Duseshrplib -Dusesitecustomize> | |
550 | ||
551 | =item * | |
552 | ||
553 | C<-Duserelocatableinc> | |
554 | ||
555 | =item * | |
556 | ||
557 | C<-Dusethreads> | |
558 | ||
559 | =back | |
7277a900 | 560 | |
d8fc5aa0 DR |
561 | If you have multiple compilers on your machine, you might also consider |
562 | compiling with C<-Dcc=$other_compiler>. | |
dc0a4df9 | 563 | |
df369d8e N |
564 | You can also consider pushing the repo to GitHub where Travis CI is enabled |
565 | which would smoke different flavors of Perl for you. | |
566 | ||
dc0a4df9 | 567 | =head3 update perlport |
7277a900 | 568 | |
347f5124 RGS |
569 | L<perlport> has a section currently named I<Supported Platforms> that |
570 | indicates which platforms are known to build in the current release. | |
571 | If necessary update the list and the indicated version number. | |
572 | ||
1dbf7599 DG |
573 | =head3 check a readonly build |
574 | ||
13f502ed | 575 | Even before other prep work, follow the steps in L</build the tarball> and test |
1dbf7599 DG |
576 | it locally. Because a perl source tarballs sets many files read-only, it could |
577 | test differently than tests run from the repository. After you're sure | |
578 | permissions aren't a problem, delete the generated directory and tarballs. | |
6a958a95 | 579 | |
6939dacb | 580 | |
2e831dfd DM |
581 | =head2 Building a release - on the day |
582 | ||
b1288acc | 583 | This section describes the actions required to make a release |
f6b1864d | 584 | that are performed near to, or on the actual release day. |
2e831dfd | 585 | |
dc0a4df9 | 586 | =head3 re-check earlier actions |
2e831dfd | 587 | |
dc0a4df9 | 588 | Review all the actions in the previous section, |
2e831dfd DM |
589 | L<"Building a release - advance actions"> to ensure they are all done and |
590 | up-to-date. | |
591 | ||
ff721450 JL |
592 | =head3 create a release branch |
593 | ||
594 | For BLEAD-POINT releases, making a release from a release branch avoids the | |
595 | need to freeze blead during the release. This is less important for | |
596 | BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in | |
597 | those cases. Create the branch by running | |
598 | ||
a88465cf | 599 | git checkout -b release-5.xx.yy |
ff721450 | 600 | |
dc0a4df9 | 601 | =head3 build a clean perl |
8c35d285 | 602 | |
1dbf7599 | 603 | Make sure you have a gitwise-clean perl directory (no modified files, |
a0db33fe | 604 | unpushed commits etc): |
8c35d285 | 605 | |
a88465cf KW |
606 | $ git status |
607 | $ git clean -dxf | |
8c35d285 | 608 | |
dc0a4df9 | 609 | then configure and build perl so that you have a Makefile and porting tools: |
8c35d285 | 610 | |
a88465cf | 611 | $ ./Configure -Dusedevel -des && make |
8c35d285 | 612 | |
a8ec9917 SH |
613 | =head3 Check module versions |
614 | ||
615 | For each Perl release since the previous release of the current branch, check | |
616 | for modules that have identical version numbers but different contents by | |
617 | running: | |
618 | ||
a88465cf | 619 | $ ./perl -Ilib Porting/cmpVERSION.pl --tag=v5.X.YY |
a8ec9917 SH |
620 | |
621 | (This is done automatically by F<t/porting/cmp_version.t> for the previous | |
622 | release of the current branch, but not for any releases from other branches.) | |
623 | ||
624 | Any modules that fail will need a version bump, plus a nudge to the upstream | |
625 | maintainer for 'cpan' upstream modules. | |
626 | ||
dc0a4df9 | 627 | =head3 update Module::CoreList |
8c35d285 | 628 | |
0429cb0e SH |
629 | =head4 Bump Module::CoreList* $VERSIONs |
630 | ||
6939dacb | 631 | If necessary, bump C<$VERSION> (there's no need to do this |
78a62309 | 632 | for every RC; in RC1, bump the version to a new clean number that will |
0429cb0e SH |
633 | appear in the final release, and leave as-is for the later RCs and final). |
634 | It may also happen that C<Module::CoreList> has been modified in blead, and | |
635 | hence has a new version number already. (But make sure it is not the same | |
636 | number as a CPAN release.) | |
637 | ||
0429cb0e SH |
638 | C<$Module::CoreList::Utils::VERSION> should always be equal to |
639 | C<$Module::CoreList::VERSION>. If necessary, bump those two versions to match | |
640 | before proceeding. | |
641 | ||
6939dacb | 642 | Once again, the files to modify are: |
77087aae AC |
643 | |
644 | =over 4 | |
645 | ||
646 | =item * | |
647 | ||
648 | F<dist/Module-CoreList/lib/Module/CoreList.pm> | |
649 | ||
650 | =item * | |
651 | ||
652 | F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> | |
653 | ||
77087aae | 654 | =back |
94691c19 | 655 | |
0429cb0e | 656 | =head4 Update C<Module::CoreList> with module version data for the new release. |
bfadf2ba | 657 | |
6a958a95 | 658 | Note that if this is a MAINT release, you should run the following actions |
1bac61bb | 659 | from the maint branch, but commit the C<CoreList.pm> changes in |
a9d1f3db LB |
660 | I<blead> and subsequently cherry-pick any releases since the last |
661 | maint release and then your recent commit. XXX need a better example | |
bfadf2ba | 662 | |
89781932 DM |
663 | [ Note that the procedure for handling Module::CoreList in maint branches |
664 | is a bit complex, and the RMG currently don't describe a full and | |
665 | workable approach. The main issue is keeping Module::CoreList | |
666 | and its version number synchronised across all maint branches, blead and | |
667 | CPAN, while having to bump its version number for every RC release. | |
668 | See this brief p5p thread: | |
669 | ||
a88465cf | 670 | Message-ID: <20130311174402.GZ2294@iabyn.com> |
89781932 DM |
671 | |
672 | If you can devise a workable system, feel free to try it out, and to | |
38e4b857 | 673 | update the RMG accordingly! |
89781932 DM |
674 | |
675 | DAPM May 2013 ] | |
676 | ||
ee64eb7d | 677 | F<corelist.pl> uses www.cpan.org to verify information about dual-lived |
218a07e7 SH |
678 | modules on CPAN. It can use a full, local CPAN mirror and/or fall back |
679 | on HTTP::Tiny to fetch package metadata remotely. | |
bfadf2ba | 680 | |
fdaa3f94 | 681 | (If you'd prefer to have a full CPAN mirror, see |
f6521f7c | 682 | L<https://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN>) |
bfadf2ba | 683 | |
6939dacb | 684 | Change to your perl checkout, and if necessary, |
bfadf2ba | 685 | |
a88465cf | 686 | $ make |
bfadf2ba | 687 | |
bf8ea215 | 688 | Then, If you have a local CPAN mirror, run: |
bfadf2ba | 689 | |
a88465cf | 690 | $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror |
bfadf2ba JV |
691 | |
692 | Otherwise, run: | |
693 | ||
a88465cf | 694 | $ ./perl -Ilib Porting/corelist.pl cpan |
bfadf2ba | 695 | |
52a66c2c | 696 | This will chug for a while, possibly reporting various warnings about |
2a720090 | 697 | badly-indexed CPAN modules unrelated to the modules actually in core. |
2ce7d676 | 698 | Assuming all goes well, it will update |
ab0bff1f | 699 | F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly |
244e6e4e | 700 | F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>. |
bfadf2ba | 701 | |
ab0bff1f | 702 | Check those files over carefully: |
bfadf2ba | 703 | |
a88465cf KW |
704 | $ git diff dist/Module-CoreList/lib/Module/CoreList.pm |
705 | $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm | |
1dbf7599 | 706 | |
00c28750 DR |
707 | =head4 Bump version in Module::CoreList F<Changes> |
708 | ||
0429cb0e | 709 | Also edit Module::CoreList's new version number in its F<Changes> file. |
f8804d60 | 710 | This file is F<dist/Module-CoreList/Changes>. |
6939dacb KE |
711 | (BLEAD-POINT releases should have had this done already as a post-release |
712 | action from the last commit.) | |
e8c01f92 | 713 | |
00c28750 DR |
714 | =head4 Add Module::CoreList version bump to perldelta |
715 | ||
14071f95 MH |
716 | Add a perldelta entry for the new Module::CoreList version. You only |
717 | need to do this if you want to add notes about the changes included | |
718 | with this version of Module::CoreList. Otherwise, its version bump | |
13f502ed | 719 | will be automatically filled in below in L</finalize perldelta>. |
70855f8b | 720 | |
da571fa1 DR |
721 | =for checklist skip RC |
722 | ||
09abf5f8 | 723 | =head4 Update C<%Module::CoreList::released> |
da571fa1 | 724 | |
09abf5f8 SH |
725 | For any release except an RC: Update this version's entry in the C<%released> |
726 | hash with today's date. | |
bfadf2ba | 727 | |
00c28750 DR |
728 | =head4 Commit Module::CoreList changes |
729 | ||
bfadf2ba | 730 | Finally, commit the new version of Module::CoreList: |
6a958a95 | 731 | (unless this is for MAINT; in which case commit it to blead first, then |
a0db33fe | 732 | cherry-pick it back). |
bfadf2ba | 733 | |
a88465cf KW |
734 | $ git commit -m 'Update Module::CoreList for 5.x.y' \ |
735 | dist/Module-CoreList/Changes \ | |
736 | dist/Module-CoreList/lib/Module/CoreList.pm \ | |
737 | dist/Module-CoreList/lib/Module/CoreList/Utils.pm | |
bfadf2ba | 738 | |
1dbf7599 DG |
739 | =head4 Rebuild and test |
740 | ||
78a62309 SH |
741 | Build and test to get the changes into the currently built lib directory and to |
742 | ensure all tests are passing. | |
1dbf7599 DG |
743 | |
744 | =head3 finalize perldelta | |
745 | ||
746 | Finalize the perldelta. In particular, fill in the Acknowledgements | |
747 | section, which can be generated with something like: | |
748 | ||
a88465cf | 749 | $ perl Porting/acknowledgements.pl v5.15.0..HEAD |
1dbf7599 | 750 | |
78a62309 SH |
751 | Fill in the "New/Updated Modules" sections now that Module::CoreList is |
752 | updated: | |
2c5d738b | 753 | |
a88465cf KW |
754 | $ ./perl -Ilib Porting/corelist-perldelta.pl \ |
755 | --mode=update pod/perldelta.pod | |
be2822b0 SH |
756 | |
757 | For a MAINT release use something like this instead: | |
758 | ||
a88465cf KW |
759 | $ ./perl -Ilib Porting/corelist-perldelta.pl 5.020001 5.020002 \ |
760 | --mode=update pod/perldelta.pod | |
2c5d738b SH |
761 | |
762 | Ideally, also fill in a summary of the major changes to each module for which | |
763 | an entry has been added by F<corelist-perldelta.pl>. | |
1dbf7599 DG |
764 | |
765 | Re-read the perldelta to try to find any embarrassing typos and thinkos; | |
766 | remove any C<TODO> or C<XXX> flags; update the "Known Problems" section | |
767 | with any serious issues for which fixes are not going to happen now; and | |
768 | run through pod and spell checkers, e.g. | |
769 | ||
a88465cf KW |
770 | $ podchecker -warnings -warnings pod/perldelta.pod |
771 | $ spell pod/perldelta.pod | |
772 | $ aspell list < pod/perldelta.pod | sort -u | |
1dbf7599 DG |
773 | |
774 | Also, you may want to generate and view an HTML version of it to check | |
775 | formatting, e.g. | |
776 | ||
a88465cf KW |
777 | $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > \ |
778 | ~/perldelta.html | |
1dbf7599 | 779 | |
95f5f2bd | 780 | You should add pod links for GitHub issue references thusly: |
9649a817 | 781 | |
a88465cf | 782 | $ perl -p -i -e'BEGIN{undef $/}; s{(GH\s+#)(\d+)}{L<$1$2|https://github.com/Perl/perl5/issues/$2>}mg' pod/perldelta.pod |
9649a817 | 783 | |
1dbf7599 DG |
784 | If you make changes, be sure to commit them. |
785 | ||
786 | =for checklist skip BLEAD-POINT MAINT RC | |
787 | ||
788 | =head3 remove stale perldeltas | |
789 | ||
790 | For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas | |
1f6591ac | 791 | from the BLEAD-POINT releases since the previous BLEAD-FINAL should have |
1dbf7599 DG |
792 | now been consolidated into the current perldelta, and hence are now just |
793 | useless clutter. They can be removed using: | |
794 | ||
a88465cf | 795 | $ git rm <file1> <file2> ... |
1dbf7599 DG |
796 | |
797 | For example, for RC0 of 5.16.0: | |
798 | ||
a88465cf KW |
799 | $ cd pod |
800 | $ git rm perldelta515*.pod | |
1dbf7599 | 801 | |
1f6591ac | 802 | =for checklist skip BLEAD-FINAL BLEAD-POINT |
1dbf7599 DG |
803 | |
804 | =head3 add recent perldeltas | |
805 | ||
806 | For the first RC for a MAINT release, copy in any recent perldeltas from | |
807 | blead that have been added since the last release on this branch. This | |
808 | should include any recent maint releases on branches older than your one, | |
809 | but not newer. For example if you're producing a 5.14.x release, copy any | |
810 | perldeltas from recent 5.10.x, 5.12.x etc maint releases, but not from | |
811 | 5.16.x or higher. Remember to | |
812 | ||
a88465cf | 813 | $ git add <file1> <file2> ... |
1dbf7599 DG |
814 | |
815 | =head3 update and commit perldelta files | |
816 | ||
817 | If you have added or removed any perldelta files via the previous two | |
818 | steps, then edit F<pod/perl.pod> to add/remove them from its table of | |
819 | contents, then run F<Porting/pod_rules.pl> to propagate your changes there | |
820 | into all the other files that mention them (including F<MANIFEST>). You'll | |
821 | need to C<git add> the files that it changes. | |
822 | ||
823 | Then build a clean perl and do a full test | |
824 | ||
a88465cf KW |
825 | $ git status |
826 | $ git clean -dxf | |
827 | $ ./Configure -Dusedevel -des | |
828 | $ make | |
829 | $ make test | |
1dbf7599 DG |
830 | |
831 | Once all tests pass, commit your changes. | |
832 | ||
6df8fd8f N |
833 | =head3 final check of perldelta placeholders |
834 | ||
835 | Check for any 'XXX' leftover section in the perldelta. | |
836 | Either fill them or remove these sections appropriately. | |
837 | ||
a88465cf | 838 | $ git grep XX pod/perldelta.pod |
6df8fd8f | 839 | |
1dbf7599 DG |
840 | =head3 build a clean perl |
841 | ||
842 | If you skipped the previous step (adding/removing perldeltas), | |
843 | again, make sure you have a gitwise-clean perl directory (no modified files, | |
844 | unpushed commits etc): | |
845 | ||
a88465cf KW |
846 | $ git status |
847 | $ git clean -dxf | |
1dbf7599 DG |
848 | |
849 | then configure and build perl so that you have a Makefile and porting tools: | |
850 | ||
a88465cf | 851 | $ ./Configure -Dusedevel -des && make |
1dbf7599 | 852 | |
1f6591ac | 853 | =for checklist skip BLEAD-FINAL BLEAD-POINT |
80dd5f25 DM |
854 | |
855 | =head3 synchronise from blead's perlhist.pod | |
856 | ||
857 | For the first RC for a MAINT release, copy in the latest | |
858 | F<pod/perlhist.pod> from blead; this will include details of newer | |
859 | releases in all branches. In theory, blead's version should be a strict | |
c26b8729 AC |
860 | superset of the one in this branch, but it's probably safest to examine the |
861 | changes first, to ensure that there's nothing in this branch that was | |
862 | forgotten from blead. An easy way to do that is with C<< git checkout -p >>, | |
863 | to selectively apply any changes from the blead version to your current | |
864 | branch: | |
865 | ||
a88465cf KW |
866 | $ git fetch origin |
867 | $ git checkout -p origin/blead pod/perlhist.pod | |
868 | $ git commit -m 'Sync perlhist from blead' pod/perlhist.pod | |
80dd5f25 | 869 | |
dc0a4df9 | 870 | =head3 update perlhist.pod |
a0db33fe | 871 | |
e8a7a70e JV |
872 | Add an entry to F<pod/perlhist.pod> with the release date, e.g.: |
873 | ||
a88465cf | 874 | David 5.10.1 2009-Aug-06 |
a0db33fe | 875 | |
a420fd35 MH |
876 | List yourself in the left-hand column, and if this is the first release |
877 | that you've ever done, make sure that your name is listed in the section | |
878 | entitled C<THE KEEPERS OF THE PUMPKIN>. | |
a0db33fe | 879 | |
56e2d9fb | 880 | I<If you're making a BLEAD-FINAL release>, also update the "SELECTED |
bd4ce907 RS |
881 | RELEASE SIZES" section with the output of |
882 | F<Porting/perlhist_calculate.pl>. | |
883 | ||
a0db33fe DM |
884 | Be sure to commit your changes: |
885 | ||
a88465cf | 886 | $ git commit -m 'Add new release to perlhist' pod/perlhist.pod |
8c35d285 | 887 | |
da571fa1 | 888 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
889 | |
890 | =head3 update patchlevel.h | |
8c35d285 | 891 | |
6a958a95 | 892 | I<You MUST SKIP this step for a BLEAD-POINT release> |
d7eb1120 | 893 | |
a42352ee DM |
894 | Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is |
895 | a final release, remove it. For example: | |
d7eb1120 | 896 | |
a88465cf KW |
897 | static const char * const local_patches[] = { |
898 | NULL | |
899 | + ,"RC1" | |
900 | #ifdef PERL_GIT_UNCOMMITTED_CHANGES | |
901 | ,"uncommitted-changes" | |
902 | #endif | |
d7eb1120 DM |
903 | |
904 | Be sure to commit your change: | |
905 | ||
a88465cf | 906 | $ git commit -m 'Bump version to RCnnn' patchlevel.h |
d7eb1120 | 907 | |
4612967b CBW |
908 | =head3 run makemeta to update META files |
909 | ||
a88465cf | 910 | $ ./perl -Ilib Porting/makemeta |
4612967b CBW |
911 | |
912 | Be sure to commit any changes (if applicable): | |
913 | ||
a88465cf KW |
914 | $ git status # any changes? |
915 | $ git commit -m 'Update META files' META.* | |
dc0a4df9 DM |
916 | |
917 | =head3 build, test and check a fresh perl | |
d7eb1120 | 918 | |
a0db33fe DM |
919 | Build perl, then make sure it passes its own test suite, and installs: |
920 | ||
a88465cf KW |
921 | $ git clean -xdf |
922 | $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest | |
a42352ee | 923 | |
a88465cf KW |
924 | # or if it's an odd-numbered version: |
925 | $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest | |
a42352ee | 926 | |
a88465cf | 927 | $ make test install |
a0db33fe | 928 | |
52a66c2c DM |
929 | Check that the output of C</tmp/perl-5.x.y-pretest/bin/perl -v> and |
930 | C</tmp/perl-5.x.y-pretest/bin/perl -V> are as expected, | |
a0db33fe | 931 | especially as regards version numbers, patch and/or RC levels, and @INC |
c5fb089a | 932 | paths. Note that as they have been built from a git working |
52a66c2c | 933 | directory, they will still identify themselves using git tags and |
01725c10 A |
934 | commits. (Note that for an odd-numbered version, perl will install |
935 | itself as C<perl5.x.y>). C<perl -v> will identify itself as: | |
936 | ||
f185f654 | 937 | This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef)) |
01725c10 | 938 | |
78957677 | 939 | where 5.X.Z is the latest tag, NNN the number of commits since this tag, |
01725c10 | 940 | and C<< deadbeef >> commit of that tag. |
52a66c2c DM |
941 | |
942 | Then delete the temporary installation. | |
943 | ||
c90225ed | 944 | =head3 create the release tag |
dc0a4df9 | 945 | |
c90225ed | 946 | Create the tag identifying this release (e.g.): |
96054f12 | 947 | |
a88465cf | 948 | $ git tag v5.11.0 -m 'First release of the v5.11 series!' |
e8c01f92 | 949 | |
6a958a95 | 950 | It is B<VERY> important that from this point forward, you not push |
f662f3b7 JV |
951 | your git changes to the Perl master repository. If anything goes |
952 | wrong before you publish your newly-created tag, you can delete | |
953 | and recreate it. Once you push your tag, we're stuck with it | |
954 | and you'll need to use a new version number for your release. | |
955 | ||
dc0a4df9 | 956 | =head3 build the tarball |
a0db33fe | 957 | |
0dcf3caa | 958 | Before you run the following, you might want to install 7-Zip (the |
0dcb816b | 959 | C<p7zip-full> package under Debian or the C<p7zip> port on MacPorts) or |
0dcf3caa LB |
960 | the AdvanceCOMP suite (e.g. the C<advancecomp> package under Debian, |
961 | or the C<advancecomp> port on macports - 7-Zip on Windows is the | |
962 | same code as AdvanceCOMP, so Windows users get the smallest files | |
963 | first time). These compress about 5% smaller than gzip and bzip2. | |
964 | Over the lifetime of your distribution this will save a lot of | |
965 | people a small amount of download time and disk space, which adds | |
966 | up. | |
967 | ||
2174049d CBW |
968 | In order to produce the C<xz> tarball, XZ Utils are required. The C<xz> |
969 | utility is included with most modern UNIX-type operating systems and | |
970 | is available for Cygwin. A Windows port is available from | |
f6521f7c | 971 | L<https://tukaani.org/xz/>. |
2174049d | 972 | |
96644a2c DG |
973 | B<IMPORTANT>: if you are on OS X, you must export C<COPYFILE_DISABLE=1> |
974 | to prevent OS X resource files from being included in your tarball. After | |
975 | creating the tarball following the instructions below, inspect it to ensure | |
976 | you don't have files like F<._foobar>. | |
977 | ||
8c35d285 JV |
978 | Create a tarball. Use the C<-s> option to specify a suitable suffix for |
979 | the tarball and directory name: | |
980 | ||
f185f654 | 981 | $ cd root/of/perl/tree |
6939dacb KE |
982 | $ make distclean # make sure distclean works |
983 | $ git clean -xdf # make sure perl and git agree on files | |
a88465cf | 984 | # git clean should not output anything! |
6939dacb | 985 | $ git status --ignored # and there's nothing lying around |
8c35d285 | 986 | |
6939dacb KE |
987 | $ perl Porting/makerel -x -s RC1 # for a release candidate |
988 | $ perl Porting/makerel -x # for the release itself | |
8c35d285 | 989 | |
6939dacb | 990 | This creates the directory F<../perl-x.y.z-RC1> or similar, copies all |
ac2aec01 | 991 | the MANIFEST files into it, sets the correct permissions on them, then |
6939dacb KE |
992 | tars it up as F<../perl-x.y.z-RC1.tar.gz>. The C<-x> also produces a |
993 | C<tar.xz> file. | |
8c35d285 | 994 | |
6480287f MT |
995 | If you're getting your tarball suffixed with -uncommitted and you're sure |
996 | your changes were all committed, you can override the suffix with: | |
997 | ||
a88465cf | 998 | $ perl Porting/makerel -x -s '' |
96054f12 | 999 | |
8c35d285 JV |
1000 | XXX if we go for extra tags and branches stuff, then add the extra details |
1001 | here | |
1002 | ||
dc0a4df9 | 1003 | Finally, clean up the temporary directory, e.g. |
a42352ee | 1004 | |
a88465cf | 1005 | $ rm -rf ../perl-x.y.z-RC1 |
a42352ee | 1006 | |
dc0a4df9 DM |
1007 | =head3 test the tarball |
1008 | ||
00c28750 | 1009 | Once you have a tarball it's time to test the tarball (not the repository). |
dc0a4df9 | 1010 | |
00c28750 | 1011 | =head4 Copy the tarball to a web server |
a42352ee | 1012 | |
6939dacb | 1013 | Copy the tarballs (.gz and .xz) to a web server somewhere you have access to. |
8c35d285 | 1014 | |
96644a2c | 1015 | =head4 Download the tarball to another machine and unpack it |
8c35d285 | 1016 | |
fdaa3f94 | 1017 | Download the tarball to some other machine. For a release candidate, |
8c35d285 | 1018 | you really want to test your tarball on two or more different platforms |
96644a2c DG |
1019 | and architectures. |
1020 | ||
1021 | =head4 Ask #p5p to test the tarball on different platforms | |
1022 | ||
1023 | Once you've verified the tarball can be downloaded and unpacked, | |
1024 | ask the #p5p IRC channel on irc.perl.org for volunteers to test the | |
1025 | tarballs on whatever platforms they can. | |
1026 | ||
1027 | If you're not confident in the tarball, you can defer this step until after | |
1028 | your own tarball testing, below. | |
8c35d285 | 1029 | |
00c28750 | 1030 | =head4 Check that F<Configure> works |
8c35d285 JV |
1031 | |
1032 | Check that basic configuration and tests work on each test machine: | |
1033 | ||
a88465cf | 1034 | $ ./Configure -des && make all minitest test |
e07c44df | 1035 | |
a88465cf KW |
1036 | # Or for a development release: |
1037 | $ ./Configure -Dusedevel -des && make all minitest test | |
f6af4394 | 1038 | |
00c28750 | 1039 | =head4 Run the test harness and install |
f6af4394 | 1040 | |
8c35d285 JV |
1041 | Check that the test harness and install work on each test machine: |
1042 | ||
a88465cf KW |
1043 | $ make distclean |
1044 | $ ./Configure -des -Dprefix=/install/path && \ | |
1045 | make all test_harness install | |
1046 | $ cd /install/path | |
8c35d285 | 1047 | |
091086c0 S |
1048 | (Remember C<-Dusedevel> above, for a development release.) |
1049 | ||
00c28750 | 1050 | =head4 Check C<perl -v> and C<perl -V> |
8c35d285 JV |
1051 | |
1052 | Check that the output of C<perl -v> and C<perl -V> are as expected, | |
1053 | especially as regards version numbers, patch and/or RC levels, and @INC | |
fdaa3f94 | 1054 | paths. |
8c35d285 JV |
1055 | |
1056 | Note that the results may be different without a F<.git/> directory, | |
1057 | which is why you should test from the tarball. | |
1058 | ||
00c28750 | 1059 | =head4 Run the Installation Verification Procedure utility |
459fc3ca | 1060 | |
a88465cf KW |
1061 | $ ./perl -Ilib ./utils/perlivp |
1062 | # Or, perhaps: | |
1063 | $ ./perl5.x.y ./utils/perlivp5.x.y | |
1064 | ... | |
1065 | All tests successful. | |
1066 | $ | |
459fc3ca | 1067 | |
00c28750 | 1068 | =head4 Compare the installed paths to the last release |
459fc3ca | 1069 | |
d60a1044 DM |
1070 | Compare the pathnames of all installed files with those of the previous |
1071 | release (i.e. against the last installed tarball on this branch which you | |
1072 | have previously verified using this same procedure). In particular, look | |
1073 | for files in the wrong place, or files no longer included which should be. | |
1074 | For example, suppose the about-to-be-released version is 5.10.1 and the | |
1075 | previous is 5.10.0: | |
1076 | ||
a88465cf KW |
1077 | cd installdir-5.10.0/ |
1078 | find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1 | |
1079 | cd installdir-5.10.1/ | |
1080 | find . -type f | sort > /tmp/f2 | |
1081 | diff -u /tmp/f[12] | |
d60a1044 | 1082 | |
091086c0 S |
1083 | =head4 Disable C<local::lib> if it's turned on |
1084 | ||
1085 | If you're using C<local::lib>, you should reset your environment before | |
1086 | performing these actions: | |
1087 | ||
a88465cf | 1088 | $ unset PERL5LIB PERL_MB_OPT PERL_LOCAL_LIB_ROOT PERL_MM_OPT |
091086c0 | 1089 | |
29205e9c | 1090 | =head4 Bootstrap the CPAN client |
d60a1044 | 1091 | |
8c35d285 JV |
1092 | Bootstrap the CPAN client on the clean install: |
1093 | ||
a88465cf | 1094 | $ bin/cpan |
8c35d285 | 1095 | |
a88465cf KW |
1096 | # Or, perhaps: |
1097 | $ bin/cpan5.xx.x | |
61a1ab54 | 1098 | |
29205e9c | 1099 | =head4 Install the Inline module with CPAN and test it |
8c35d285 | 1100 | |
a42352ee DM |
1101 | Try installing a popular CPAN module that's reasonably complex and that |
1102 | has dependencies; for example: | |
8c35d285 | 1103 | |
a88465cf KW |
1104 | CPAN> install Inline::C |
1105 | CPAN> quit | |
8c35d285 JV |
1106 | |
1107 | Check that your perl can run this: | |
1108 | ||
a88465cf KW |
1109 | $ bin/perl -Ilib -lwe "use Inline C => q[int f() { return 42;}]; print f" |
1110 | 42 | |
1111 | $ | |
8c35d285 | 1112 | |
00c28750 | 1113 | =head4 Make sure that perlbug works |
8c35d285 | 1114 | |
00c28750 | 1115 | Test L<perlbug> with the following: |
47b1f096 | 1116 | |
a88465cf KW |
1117 | $ bin/perlbug |
1118 | ... | |
1119 | Subject: test bug report | |
1120 | Local perl administrator [yourself]: | |
1121 | Editor [vi]: | |
1122 | Module: | |
1123 | Category [core]: | |
1124 | Severity [low]: | |
1125 | (edit report) | |
1126 | Action (Send/Display/Edit/Subject/Save to File): f | |
1127 | Name of file to save message in [perlbug.rep]: | |
47b1f096 DM |
1128 | |
1129 | and carefully examine the output (in F<perlbug.rep]>), especially | |
8166b4e0 | 1130 | the "Locally applied patches" section. |
47b1f096 | 1131 | |
da571fa1 | 1132 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
1133 | |
1134 | =head3 monitor smokes | |
47b1f096 | 1135 | |
1dbf7599 DG |
1136 | XXX This is probably irrelevant if working on a release branch, though |
1137 | MAINT or RC might want to push a smoke branch and wait. | |
1138 | ||
f6af4394 DM |
1139 | Wait for the smoke tests to catch up with the commit which this release is |
1140 | based on (or at least the last commit of any consequence). | |
7277a900 | 1141 | |
f6af4394 DM |
1142 | Then check that the smoke tests pass (particularly on Win32). If not, go |
1143 | back and fix things. | |
7277a900 | 1144 | |
6a958a95 | 1145 | Note that for I<BLEAD-POINT> releases this may not be practical. It takes a |
1eefd7d5 | 1146 | long time for the smokers to catch up, especially the Win32 |
6a958a95 DM |
1147 | smokers. This is why we have a RC cycle for I<MAINT> and I<BLEAD-FINAL> |
1148 | releases, but for I<BLEAD-POINT> releases sometimes the best you can do is | |
1149 | to plead with people on IRC to test stuff on their platforms, fire away, | |
1150 | and then hope for the best. | |
7277a900 | 1151 | |
dc0a4df9 | 1152 | =head3 upload to PAUSE |
7277a900 | 1153 | |
f6af4394 | 1154 | Once smoking is okay, upload it to PAUSE. This is the point of no return. |
db3f805e JV |
1155 | If anything goes wrong after this point, you will need to re-prepare |
1156 | a new release with a new minor version or RC number. | |
1157 | ||
a88465cf | 1158 | https://pause.perl.org/ |
a14438df | 1159 | |
6939dacb | 1160 | (Log in, then select 'Upload a file to CPAN') |
a14438df | 1161 | |
45924287 RS |
1162 | If your workstation is not connected to a high-bandwidth, |
1163 | high-reliability connection to the Internet, you should probably use the | |
1164 | "GET URL" feature (rather than "HTTP UPLOAD") to have PAUSE retrieve the | |
1165 | new release from wherever you put it for testers to find it. This will | |
1166 | eliminate anxious gnashing of teeth while you wait to see if your | |
1167 | 15 megabyte HTTP upload successfully completes across your slow, twitchy | |
96644a2c DG |
1168 | cable modem. |
1169 | ||
96644a2c | 1170 | I<Remember>: if your upload is partially successful, you |
c27b4e97 | 1171 | may need to contact a PAUSE administrator or even bump the version of perl. |
45924287 | 1172 | |
6939dacb KE |
1173 | Upload the .gz and .xz versions of the tarball. |
1174 | ||
1175 | Note: You can also use the command-line utility to upload your tarballs, if | |
1176 | you have it configured: | |
1177 | ||
a88465cf KW |
1178 | cpan-upload perl-5.X.Y.tar.gz |
1179 | cpan-upload perl-5.X.Y.tar.xz | |
f6af4394 | 1180 | |
1dbf7599 | 1181 | Do not proceed any further until you are sure that your tarballs are on CPAN. |
6df8fd8f N |
1182 | Check your authors directory metacpan.org to confirm that your uploads have |
1183 | been successful. | |
1184 | ||
a88465cf | 1185 | https://metacpan.org/author/YOUR_PAUSE_ID |
c27b4e97 | 1186 | |
1dbf7599 | 1187 | =for checklist skip RC BLEAD-POINT |
00c28750 DR |
1188 | |
1189 | =head3 wait for indexing | |
1190 | ||
1dbf7599 | 1191 | I<You MUST SKIP this step for RC and BLEAD-POINT> |
76526317 FR |
1192 | |
1193 | Wait until you receive notification emails from the PAUSE indexer | |
1194 | confirming that your uploads have been received. IMPORTANT -- you will | |
1195 | probably get an email that indexing has failed, due to module permissions. | |
1196 | This is considered normal. | |
1197 | ||
da571fa1 | 1198 | =for checklist skip BLEAD-POINT |
dc0a4df9 DM |
1199 | |
1200 | =head3 disarm patchlevel.h | |
f6af4394 | 1201 | |
6a958a95 | 1202 | I<You MUST SKIP this step for BLEAD-POINT release> |
113f3f4c | 1203 | |
a42352ee | 1204 | Disarm the F<patchlevel.h> change; for example, |
d7eb1120 | 1205 | |
a88465cf KW |
1206 | static const char * const local_patches[] = { |
1207 | NULL | |
1208 | - ,"RC1" | |
1209 | #ifdef PERL_GIT_UNCOMMITTED_CHANGES | |
1210 | ,"uncommitted-changes" | |
1211 | #endif | |
d7eb1120 DM |
1212 | |
1213 | Be sure to commit your change: | |
1214 | ||
a88465cf | 1215 | $ git commit -m 'Disarm RCnnn bump' patchlevel.h |
dc0a4df9 DM |
1216 | |
1217 | =head3 announce to p5p | |
2e831dfd | 1218 | |
6939dacb | 1219 | Mail perl5-porters@perl.org to announce your new release, with a quote you prepared earlier. |
6bd57ce2 | 1220 | Get the SHA256 digests from the PAUSE email responses. |
f6af4394 | 1221 | |
098d30ef | 1222 | Use the template at Porting/release_announcement_template.txt |
dc0a4df9 | 1223 | |
a8cecd9d RS |
1224 | Send a carbon copy to C<noc@metacpan.org> |
1225 | ||
5124a906 RL |
1226 | If your email does not appear on the list, but does not obviously bounce |
1227 | either, check that the email you are sending from is subscribed to the list. | |
1228 | ||
ff721450 JL |
1229 | =head3 merge release branch back to blead |
1230 | ||
c90225ed | 1231 | Merge the (local) release branch back into master now, and delete it. |
ff721450 | 1232 | |
a88465cf KW |
1233 | git checkout blead |
1234 | git pull | |
1235 | git merge release-5.xx.yy | |
1236 | git push | |
1237 | git branch -d release-5.xx.yy | |
ff721450 | 1238 | |
121e9ff0 SH |
1239 | Note: The merge will create a merge commit if other changes have been pushed |
1240 | to blead while you've been working on your release branch. Do NOT rebase your | |
1241 | branch to avoid the merge commit (as you might normally do when merging a | |
1242 | small branch into blead) since doing so will invalidate the tag that you | |
1243 | created earlier. | |
1244 | ||
c90225ed SH |
1245 | =head3 publish the release tag |
1246 | ||
1247 | Now that you've shipped the new perl release to PAUSE and pushed your changes | |
1248 | to the Perl master repository, it's time to publish the tag you created | |
1249 | earlier too (e.g.): | |
1250 | ||
a88465cf | 1251 | $ git push origin tag v5.11.0 |
c90225ed | 1252 | |
dc0a4df9 | 1253 | =head3 update epigraphs.pod |
f6af4394 | 1254 | |
85531b0a | 1255 | Add your quote to F<Porting/epigraphs.pod> and commit it. |
70d95cc9 SH |
1256 | You can include the customary link to the release announcement even before your |
1257 | message reaches the web-visible archives by looking for the X-List-Archive | |
1258 | header in your message after receiving it back via perl5-porters. | |
dc0a4df9 | 1259 | |
b02b3ec7 DR |
1260 | =head3 blog about your epigraph |
1261 | ||
1262 | If you have a blog, please consider writing an entry in your blog explaining | |
1263 | why you chose that particular quote for your epigraph. | |
1264 | ||
0f4e030a KE |
1265 | =head3 update the link to the latest perl on perlweb |
1266 | ||
1267 | Submit a pull request to L<https://github.com/perlorg/perlweb> to update the | |
1268 | link in F<docs/dev/perl5/index.html> to point to your release. | |
1269 | ||
da571fa1 DR |
1270 | =for checklist skip RC |
1271 | ||
d274ee9d SH |
1272 | =head3 Release schedule |
1273 | ||
1274 | I<You MUST SKIP this step for RC> | |
1275 | ||
1276 | Tick the entry for your release in F<Porting/release_schedule.pod>. | |
1277 | ||
1278 | =for checklist skip RC | |
1279 | ||
dc0a4df9 | 1280 | =head3 Module::CoreList nagging |
85531b0a | 1281 | |
bc4c40f2 | 1282 | I<You MUST SKIP this step for RC> |
8c35d285 | 1283 | |
75a012fe DM |
1284 | Remind the current maintainer of C<Module::CoreList> to push a new release |
1285 | to CPAN. | |
7277a900 | 1286 | |
da571fa1 | 1287 | =for checklist skip RC |
dc0a4df9 DM |
1288 | |
1289 | =head3 new perldelta | |
a2cba4bc | 1290 | |
bc4c40f2 | 1291 | I<You MUST SKIP this step for RC> |
7277a900 | 1292 | |
bcfe7366 | 1293 | Create a new perldelta. |
5ef3945b | 1294 | |
bcfe7366 | 1295 | =over 4 |
8e967a1c | 1296 | |
bcfe7366 | 1297 | =item * |
8e967a1c | 1298 | |
bcfe7366 | 1299 | Confirm that you have a clean checkout with no local changes. |
c5b87fed | 1300 | |
bcfe7366 | 1301 | =item * |
17163f85 | 1302 | |
6939dacb | 1303 | Run: |
a88465cf | 1304 | perl Porting/new-perldelta.pl |
8e967a1c | 1305 | |
bcfe7366 | 1306 | =item * |
17163f85 | 1307 | |
bcfe7366 | 1308 | Run the C<git add> commands it outputs to add new and modified files. |
7277a900 | 1309 | |
bcfe7366 | 1310 | =item * |
7277a900 | 1311 | |
bcfe7366 | 1312 | Verify that the build still works, by running C<./Configure> and |
e0373c35 | 1313 | C<make test_porting>. (On Win32 use the appropriate make utility). |
17163f85 | 1314 | |
bcfe7366 | 1315 | =item * |
17163f85 | 1316 | |
bcfe7366 NC |
1317 | If F<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>, |
1318 | run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail. | |
1319 | Skip to the end of its test output to see the options it offers you. | |
57433fbf | 1320 | |
bcfe7366 | 1321 | =item * |
75a012fe | 1322 | |
bcfe7366 | 1323 | When C<make test_porting> passes, commit the new perldelta. |
75a012fe | 1324 | |
a88465cf | 1325 | git commit -m'New perldelta for 5.X.Y' |
6939dacb | 1326 | |
bcfe7366 | 1327 | =back |
75a012fe | 1328 | |
21768cb3 | 1329 | At this point you may want to compare the commit with a previous bump to |
ac2aec01 | 1330 | see if they look similar. See commit ba03bc34a4 for an example of a |
75a012fe | 1331 | previous version bump. |
57433fbf | 1332 | |
30f926b5 | 1333 | =for checklist skip MAINT RC |
dc0a4df9 DM |
1334 | |
1335 | =head3 bump version | |
57433fbf | 1336 | |
30f926b5 | 1337 | I<You MUST SKIP this step for RC and MAINT> |
dc0a62a1 | 1338 | |
6a958a95 DM |
1339 | If this was a BLEAD-FINAL release (i.e. the first release of a new maint |
1340 | series, 5.x.0 where x is even), then bump the version in the blead branch | |
1341 | in git, e.g. 5.12.0 to 5.13.0. | |
17163f85 | 1342 | |
6d5e92cd FC |
1343 | First, add a new feature bundle to F<regen/feature.pl>, initially by just |
1344 | copying the exiting entry, and bump the file's $VERSION (after the __END__ | |
1345 | marker); e.g. | |
17163f85 | 1346 | |
a88465cf KW |
1347 | "5.14" => [qw(switch say state unicode_strings)], |
1348 | + "5.15" => [qw(switch say state unicode_strings)], | |
addebd58 | 1349 | |
57fef7cc FC |
1350 | Run F<regen/feature.pl> to propagate the changes to F<lib/feature.pm>. |
1351 | ||
dc0a4df9 DM |
1352 | Then follow the section L<"Bump the version number"> to bump the version |
1353 | in the remaining files and test and commit. | |
17163f85 | 1354 | |
30f926b5 JL |
1355 | If this was a BLEAD-POINT release, then just follow the section |
1356 | L<"Bump the version number">. | |
1357 | ||
2136887a DG |
1358 | After bumping the version, follow the section L<"update INSTALL"> to |
1359 | ensure all version number references are correct. | |
17163f85 | 1360 | |
5f9f8ddf SH |
1361 | (Note: The version is NOT bumped immediately after a MAINT release in order |
1362 | to avoid confusion and wasted time arising from bug reports relating to | |
1363 | "intermediate versions" such as 5.20.1-and-a-bit: If the report is caused | |
1364 | by a bug that gets fixed in 5.20.2 and this intermediate version already | |
1365 | calls itself 5.20.2 then much time can be wasted in figuring out why there | |
1366 | is a failure from something that "should have been fixed". If the bump is | |
1367 | late then there is a much smaller window of time for such confusing bug | |
1368 | reports to arise. (The opposite problem -- trying to figure out why there | |
1369 | *is* a bug in something calling itself 5.20.1 when in fact the bug was | |
1370 | introduced later -- shouldn't arise for MAINT releases since they should, | |
1371 | in theory, only contain bug fixes but never regressions.)) | |
1372 | ||
d5c37431 NC |
1373 | =head3 clean build and test |
1374 | ||
74c5eae8 KE |
1375 | Run a clean build and test to make sure nothing obvious is broken. This is |
1376 | very important, as commands run after this point must be run using the perl | |
1377 | executable built with the bumped version number. | |
1378 | ||
1379 | $ git clean -xdf | |
1380 | $ ./Configure -des -Dusedevel | |
1381 | $ make | |
1382 | $ make test | |
d5c37431 NC |
1383 | |
1384 | In particular, F<Porting/perldelta_template.pod> is intentionally exempted | |
1385 | from podchecker tests, to avoid false positives about placeholder text. | |
1386 | However, once it's copied to F<pod/perldelta.pod> the contents can now | |
5cd8f091 | 1387 | cause test failures. Problems should be resolved by doing one of the |
ef4474b5 KW |
1388 | following: |
1389 | ||
1390 | =over | |
1391 | ||
1392 | =item 1 | |
1393 | ||
1394 | Replace placeholder text with correct text. | |
1395 | ||
1396 | =item 2 | |
1397 | ||
1398 | If the problem is from a broken placeholder link, you can add it to the | |
1399 | array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines | |
1400 | containing such links should be marked with C<XXX> so that they get | |
1401 | cleaned up before the next release. | |
1402 | ||
1403 | =item 3 | |
1404 | ||
1405 | Following the instructions output by F<t/porting/podcheck.t> on how to | |
1406 | update its exceptions database. | |
1407 | ||
1408 | =back | |
d5c37431 | 1409 | |
dc0a4df9 DM |
1410 | =head3 push commits |
1411 | ||
1412 | Finally, push any commits done above. | |
1413 | ||
a88465cf | 1414 | $ git push origin .... |
dc0a4df9 | 1415 | |
da571fa1 | 1416 | =for checklist skip BLEAD-POINT MAINT RC |
dc0a4df9 DM |
1417 | |
1418 | =head3 create maint branch | |
17163f85 | 1419 | |
6a958a95 | 1420 | I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT> |
17163f85 | 1421 | |
6a958a95 DM |
1422 | If this was a BLEAD-FINAL release (i.e. the first release of a new maint |
1423 | series, 5.x.0 where x is even), then create a new maint branch based on | |
1424 | the commit tagged as the current release. | |
7277a900 | 1425 | |
233ca920 JV |
1426 | Assuming you're using git 1.7.x or newer: |
1427 | ||
a88465cf KW |
1428 | $ git checkout -b maint-5.12 v5.12.0 |
1429 | $ git push origin -u maint-5.12 | |
addebd58 | 1430 | |
dc0a4df9 | 1431 | |
da571fa1 DR |
1432 | =for checklist skip BLEAD-POINT MAINT RC |
1433 | ||
d5722260 DK |
1434 | =head3 make the maint branch available in the APC |
1435 | ||
1436 | Clone the new branch into /srv/gitcommon/branches on camel so the APC will | |
1437 | receive its changes. | |
1438 | ||
a88465cf KW |
1439 | $ git clone --branch maint-5.14 /gitroot/perl.git \ |
1440 | ? /srv/gitcommon/branches/perl-5.14.x | |
1441 | $ chmod -R g=u /srv/gitcommon/branches/perl-5.14.x | |
d5722260 DK |
1442 | |
1443 | And nag the sysadmins to make this directory available via rsync. | |
1444 | ||
1dbf7599 DG |
1445 | XXX Who are the sysadmins? Contact info? |
1446 | ||
da571fa1 | 1447 | =for checklist skip BLEAD-POINT RC |
d5722260 | 1448 | |
f6b1864d | 1449 | =head3 copy perldelta.pod to blead |
addebd58 | 1450 | |
6a958a95 | 1451 | I<You MUST SKIP this step for RC, BLEAD-POINT> |
8c35d285 | 1452 | |
f6b1864d | 1453 | Copy the perldelta.pod for this release into blead; for example: |
7277a900 | 1454 | |
f185f654 KW |
1455 | $ cd ..../blead |
1456 | $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod #for example | |
1457 | $ git add pod/perl5101delta.pod | |
75a012fe | 1458 | |
5d0d3de0 SH |
1459 | Don't forget to set the NAME correctly in the new file (e.g. perl5101delta |
1460 | rather than perldelta). | |
1461 | ||
0aef0fe5 | 1462 | Edit F<pod/perl.pod> to add an entry for the file, e.g.: |
75a012fe | 1463 | |
a88465cf | 1464 | perl5101delta Perl changes in version 5.10.1 |
bc4c40f2 | 1465 | |
75a012fe | 1466 | Then rebuild various files: |
7277a900 | 1467 | |
a88465cf | 1468 | $ perl Porting/pod_rules.pl |
75a012fe | 1469 | |
c90225ed | 1470 | Finally, commit and push: |
75a012fe | 1471 | |
a88465cf KW |
1472 | $ git commit -a -m 'Add perlXXXdelta' |
1473 | $ git push origin .... | |
dc0a4df9 | 1474 | |
819435de | 1475 | =for checklist skip BLEAD-POINT |
7277a900 | 1476 | |
819435de | 1477 | =head3 copy perlhist.pod entries to blead |
1dbf7599 | 1478 | |
f6af4394 | 1479 | Make sure any recent F<pod/perlhist.pod> entries are copied to |
80dd5f25 | 1480 | F<perlhist.pod> on blead. e.g. |
7277a900 | 1481 | |
a88465cf | 1482 | 5.8.9 2008-Dec-14 |
7277a900 | 1483 | |
dc0a4df9 | 1484 | =head3 Relax! |
a3738a12 | 1485 | |
bc4c40f2 JV |
1486 | I<You MUST RETIRE to your preferred PUB, CAFE or SEASIDE VILLA for some |
1487 | much-needed rest and relaxation>. | |
8c35d285 JV |
1488 | |
1489 | Thanks for releasing perl! | |
1490 | ||
b28f69c2 Z |
1491 | =head2 Building a release - the day after |
1492 | ||
2277a2fb | 1493 | =for checklist skip BLEAD-FINAL MAINT RC |
042e7a25 | 1494 | |
ab0bff1f | 1495 | =head3 update Module::CoreList |
042e7a25 DG |
1496 | |
1497 | I<After a BLEAD-POINT release only> | |
1498 | ||
1499 | After Module::CoreList has shipped to CPAN by the maintainer, update | |
1500 | Module::CoreList in the source so that it reflects the new blead | |
ab0bff1f SH |
1501 | version number: |
1502 | ||
1503 | =over 4 | |
1504 | ||
1505 | =item * | |
1506 | ||
1507 | Update F<Porting/Maintainers.pl> to list the new DISTRIBUTION on CPAN, | |
1508 | which should be identical to what is currently in blead. | |
1509 | ||
1510 | =item * | |
1511 | ||
22cd9322 CBW |
1512 | Bump the $VERSION in F<dist/Module-CoreList/lib/Module/CoreList.pm> |
1513 | and F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>. | |
ab0bff1f SH |
1514 | |
1515 | =item * | |
1516 | ||
1517 | If you have a local CPAN mirror, run: | |
1518 | ||
a88465cf | 1519 | $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror |
ab0bff1f SH |
1520 | |
1521 | Otherwise, run: | |
1522 | ||
a88465cf | 1523 | $ ./perl -Ilib Porting/corelist.pl cpan |
ab0bff1f | 1524 | |
a4a5107a | 1525 | This will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and |
244e6e4e SH |
1526 | F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before, |
1527 | but this time adding new sections for the next BLEAD-POINT release. | |
ab0bff1f SH |
1528 | |
1529 | =item * | |
1530 | ||
1531 | Add the new $Module::CoreList::VERSION to | |
1532 | F<dist/Module-CoreList/Changes>. | |
1533 | ||
1534 | =item * | |
1535 | ||
ab0bff1f SH |
1536 | Remake perl to get your changed .pm files propagated into F<lib/> and |
1537 | then run at least the F<dist/Module-CoreList/t/*.t> tests and the | |
1538 | test_porting makefile target to check that they're ok. | |
1539 | ||
a88465cf KW |
1540 | $ cd t; ./TEST ../dist/Module-CoreList/t/*.t |
1541 | $ make test_porting | |
5124a906 | 1542 | |
ab0bff1f SH |
1543 | =item * |
1544 | ||
1545 | Run | |
1546 | ||
f185f654 | 1547 | $ ./perl -Ilib -MModule::CoreList \ |
a88465cf | 1548 | -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"' |
ab0bff1f SH |
1549 | |
1550 | and check that it outputs "ok" to prove that Module::CoreList now knows | |
1551 | about blead's current version. | |
1552 | ||
1553 | =item * | |
1554 | ||
1555 | Commit and push your changes. | |
1556 | ||
a88465cf KW |
1557 | $ git add -u |
1558 | $ git commit -m "Prepare Module::Corelist for 5.XX.Y" | |
1559 | $ git push origin | |
5124a906 | 1560 | |
ab0bff1f | 1561 | =back |
042e7a25 | 1562 | |
dc0a4df9 DM |
1563 | =head3 check tarball availability |
1564 | ||
1565 | Check various website entries to make sure the that tarball has appeared | |
1566 | and is properly indexed: | |
1567 | ||
b28f69c2 Z |
1568 | =over 4 |
1569 | ||
1570 | =item * | |
1571 | ||
f6521f7c | 1572 | Check your author directory under L<https://www.cpan.org/authors/id/> |
98df743a | 1573 | to ensure that the tarballs are available on the website. |
b28f69c2 Z |
1574 | |
1575 | =item * | |
1576 | ||
a95b3d6a KW |
1577 | Check F</src> on CPAN (on a fast mirror) to ensure that links to |
1578 | the new tarballs have appeared: There should be links in F</src/5.0> | |
ac2aec01 | 1579 | (which is accumulating all new versions), and (for BLEAD-FINAL and |
a95b3d6a | 1580 | MAINT only) an appropriate mention in F</src/README.html> (which describes |
ac2aec01 | 1581 | the latest versions in each stable branch, with links). |
98df743a | 1582 | |
a95b3d6a KW |
1583 | The F</src/5.0> links should appear automatically, some hours after upload. |
1584 | If they don't, or the F</src> description is inadequate, | |
98df743a | 1585 | ask Ask <ask@perl.org>. |
b28f69c2 Z |
1586 | |
1587 | =item * | |
1588 | ||
f6521f7c | 1589 | Check L<https://www.cpan.org/src/> to ensure that the F</src> updates |
98df743a Z |
1590 | have been correctly mirrored to the website. |
1591 | If they haven't, ask Ask <ask@perl.org>. | |
1592 | ||
1593 | =item * | |
b28f69c2 | 1594 | |
c23f766f DB |
1595 | Check L<https://metacpan.org> to see if it has indexed the distribution. |
1596 | It should be visible at a URL like C<https://metacpan.org/release/DAPM/perl-5.10.1>. | |
b28f69c2 | 1597 | |
dc0a4df9 | 1598 | =back |
b28f69c2 | 1599 | |
1dbf7599 DG |
1600 | =head3 update release manager's guide |
1601 | ||
1602 | Go over your notes from the release (you did take some, right?) and update | |
1603 | F<Porting/release_managers_guide.pod> with any fixes or information that | |
1604 | will make life easier for the next release manager. | |
1605 | ||
da571fa1 | 1606 | =for checklist end |
b28f69c2 | 1607 | |
7277a900 GS |
1608 | =head1 SOURCE |
1609 | ||
f6af4394 | 1610 | Based on |
4b05bc8e | 1611 | L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2009-05/msg00608.html>, |
f6af4394 | 1612 | plus a whole bunch of other sources, including private correspondence. |
7277a900 GS |
1613 | |
1614 | =cut | |
1615 |