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