X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Frelease_managers_guide.pod;h=60ef4efd4ecc5e81e354079730215764fbc0f333;hb=8d4ff56f76907d1619ddc5fd7040d3823057ec47;hp=09b9e0773b686580f365c762ea4d4b77be6a28c7;hpb=dc0a62a1fb49c5436d458316262c2453e0848f7f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod index 09b9e07..60ef4ef 100644 --- a/Porting/release_managers_guide.pod +++ b/Porting/release_managers_guide.pod @@ -1,25 +1,28 @@ - =head1 NAME release_managers_guide - Releasing a new version of perl 5.x -XXX as of Jul 2009, this file is still a work-in-progress - DAPM +As of August 2009, this file is mostly complete, although it is missing +some detail on doing a major release (e.g. 5.10.0 -> 5.12.0). Note that +things change at each release, so there may be new things not covered +here, or tools may need updating. =head1 SYNOPSIS This document describes the series of tasks required - some automatic, some manual - to produce a perl release of some description, be that a snaphot, -release candidate, or final release. +release candidate, or final, numbered release of maint or blead. -The release process is primarily executed by the current pumpking. +The release process has traditionally been executed by the current +pumpking. -This document both helps as a check-list for the pumpking and is -a base for ideas on how the various tasks could be automated or -distributed. +This document both helps as a check-list for the release engineer +and is a base for ideas on how the various tasks could be automated +or distributed. -The outline of a release cycle is as follows: +The outline of a typical release cycle is as follows: - (5.10.1 is released, and post-release action have been done) + (5.10.1 is released, and post-release actions have been done) ...time passes... @@ -30,7 +33,9 @@ The outline of a release cycle is as follows: a few weeks before the release, a number of steps are performed, including bumping the version to 5.10.2 - + + ...a few weeks passes... + perl-5.10.2-RC1 is released perl-5.10.2 is released @@ -42,142 +47,120 @@ The outline of a release cycle is as follows: =head1 DETAILS +Some of the tasks described below apply to all four types of +release of Perl. (snapshot, RC, final release of maint, final +release of blead). Some of these tasks apply only to a subset +of these release types. If a step does not apply to a given +type of release, you will see a notation to that effect at +the beginning of the step. -=head2 Building a snapshot - -A snapshot is intended to encourage in-depth testing from time-to-time, -for example after a key point in the stabilisation of a branch. It -requires less steps than a full release, and the version number of perl in -the tarball will usually still be the old one. +=head2 Release types =over 4 -=item * - -As there are no regular smokes [ XXX yet - please fix?] find out about the -state of VMS. If it's bad, think again. - -=item * - -Rebuild META.yml: - - $ rm META.yml - $ make META.yml - -and commit it if it's changed. +=item Snapshot -=item * - -Check that the manifest is sorted and correct: - - $ make distclean - $ perl Porting/manisort - $ perl Porting/manicheck - -=item * - -If this is a release candidate or final release, add an entry to -F with the current date, e.g. - - 5.8.9-RC1 2008-Nov-10 - -Make sure the correct pumpking is listed, and if this is your first time, -append your name to C. - -=item * +A snapshot is intended to encourage in-depth testing from time-to-time, +for example after a key point in the stabilisation of a branch. It +requires fewer steps than a full release, and the version number of perl in +the tarball will usually be the same as that of the previous release. -Build perl, then make sure it passes its own test suite, and installs. +=item Release Candidate (RC) -=item * +A release candidate is an attempt to produce a tarball that is a close as +possible to the final release. Indeed, unless critical faults are found +during the RC testing, the final release will be identical to the RC +barring a few minor fixups (updating the release date in F, +removing the RC status from F, etc). If faults are found, +then the fixes should be put into a new release candidate, never directly +into a final release. -Create a tarball. Use the C<-s> option to specify a suitable suffix for -the tarball and directory name: +=item Stable/Maint release - $ cd root/of/perl/tree - $ git clean -xdf # make sure perl and git agree on files +At this point you should have a working release candidate with few or no +changes since. - $ perl Porting/makerel -s `git describe` # for a snapshot - $ perl Porting/makerel -s RC1 # for a release candidate - $ perl Porting/makerel # for a final release +It's essentially the same procedure as for making a release candidate, but +with a whole bunch of extra post-release steps. -This creates the directory F<../perl-x.y.z-RC1> or similar, copies all -the MANIFEST files into it, sets the correct permissions on them, -adds DOS line endings to some, then tars it up as -F<../perl-x.y.z-RC1.tar.gz>. +=item Blead release -XXX if we go for extra tags and branches stuff, then add the extra details -here +It's essentially the same procedure as for making a release candidate, but +with a whole bunch of extra post-release steps. -=item * +=back -Copy the tarball to a web server somewhere you have access to. +=head2 Prerequisites -=item * +Before you can make an official release of perl, there are a few +hoops you need to jump through: -Download the tarball to some other machine (for a release candidate, to two or -more servers: IRC is good for this). +=over 4 -=item * +=item PAUSE account -Check that C<./Configure -des && make all test> works in one place. +I -=item * +Make sure you have a PAUSE account suitable for uploading a perl release. +If you don't have a PAUSE account, then request one: -Check that C<./Configure ... && make all test_harness install> works. + https://pause.perl.org/pause/query?ACTION=request_id -=item * +Check that your account is allowed to upload perl distros: goto +https://pause.perl.org/, login, then select 'upload file to CPAN'; there +should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas +König to add your ID to the list of people allowed to upload something +called perl. You can find Andreas' email address at: -Check that the output of C and C are as expected, -especially as regards version numbers, patch and/or RC levels, and @INC -paths. Note that the results may be different without a F<.git/> directory, -which is why you should test from the tarball. + https://pause.perl.org/pause/query?ACTION=pause_04imprint -=item * +=item CPAN mirror -Bootstrap the CPAN client on the clean install. +Some release engineering steps require a full mirror of the CPAN. +Work to fall back to using a remote mirror via HTTP is incomplete +but ongoing. (No, a minicpan mirror is not sufficient) -=item * +=item git checkout and commit bit -Install CPANPLUS. -XXX pick something new; this is now bundled +You will need a working C installation, checkout of the perl +git repository and perl commit bit. For information about working +with perl and git, see F. -=item * +If you are not yet a perl committer, you won't be able to make a +release. Have a chat with whichever evil perl porter tried to talk +you into the idea in the first place to figure out the best way to +resolve the issue. -Bootstrap the CPANPLUS client. -=item * +=item Quotation for release announcement epigraph -Install an XS module. +I -=item * +For a numbered blead or maint release of perl, you will need a quotation +to use as an epigraph to your release announcement. (There's no harm +in having one for a snapshot, but it's not required). -If all is well, announce the snaphot to p5p. (For a release candidate, -instead follow the further steps described later.) =back -=head2 Actions prior to the first release candidate -A week or two before the first release candidate, there are some additional -tasks you should perform (actually, some of these should be done regularly -anyway, but they definitely need doing now): +=head2 Building a release - advance actions + +The work of building a release candidate for a numbered release of +perl generally starts several weeks before the first release candidate. +Some of the following steps should be done regularly, but all I be +done in the run up to a release. =over 4 =item * -Check F for consistency; both these commands should -produce no output: - - perl Porting/Maintainers --checkmani - perl Porting/Maintainers --checkmani lib/ ext/ - -=item * +I Ensure that dual-life CPAN modules are synchronised with CPAN. Basically, run the following: - ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs + $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs to see any inconsistencies between the core and CPAN versions of distros, then fix the core, or cajole CPAN authors as appropriate. See also the @@ -186,10 +169,18 @@ C<-c cachedir> option to avoid repeated CPAN downloads. To see which core distro versions differ from the current CPAN versions: - ./perl -Ilib Porting/core-cpan-diff -x -a + $ ./perl -Ilib Porting/core-cpan-diff -x -a + +If you are making a maint release, run C on both blead and +maint, then diff the two outputs. Compare this with what you expect, and if +necessary, fix things up. For example, you might think that both blead +and maint are synchronised with a particular CPAN module, but one might +have some extra changes. =item * +I + Ensure dual-life CPAN modules are stable, which comes down to: for each module that fails its regression tests on $current @@ -212,10 +203,21 @@ Ensure dual-life CPAN modules are stable, which comes down to: =item * +I + Similarly, monitor the smoking of core tests, and try to fix. =item * +I + +Similarly, monitor the smoking of perl for compiler warnings, and try to +fix. + +=item * + +I + Run F to compare the current source tree with the previous version to check for for modules that have identical version numbers but different contents, e.g.: @@ -237,24 +239,35 @@ Once all version numbers have been bumped, re-run the checks. Then run again without the -x option, to check that dual-life modules are also sensible. - =item * +I + Get perldelta in a mostly finished state. -XXX expand + +Peruse F, and try to make sure that +every section it lists is, if necessary, populated and complete. Copy +edit the whole document. =item * -Bump the perl version number (e.g. from 5.10.0 to 5.10.1). +I + +A week or two before the first release candidate, bump the perl version +number (e.g. from 5.10.0 to 5.10.1), to allow sufficient time for testing +and smoking with the target version built into the perl executable. For +subsequent release candidates and the final release, it it not necessary +to bump the version further. There is a tool to semi-automate this process. It works in two stages. First, it generates a list of suggested changes, which you review and edit; then you feed this list back and it applies the edits. So, first -scan the source dir looking for likely candidates: +scan the source directory looking for likely candidates. The command line +arguments are the old and new version numbers, and -s means scan: $ Porting/bump-perl-version -s 5.10.0 5.10.1 > /tmp/scan -This produces a file containing a list of suggested edits, eg: +This produces a file containing a list of suggested edits, e.g.: NetWare/Makefile @@ -263,9 +276,10 @@ This produces a file containing a list of suggested edits, eg: i.e. in the file F, line 89 would be changed as shown. Review the file carefully, and delete any -/+ line pairs that you don't -want changing. Remember that this tool is largely just grepping for '5.10.0' -or whatever, so it will generate false positives. Be careful not change -text like "this was fixed in 5.10.0"! Then run: +want changing. You can also edit just the C<+> line to change the +suggested replacement text. Remember that this tool is largely just +grepping for '5.10.0' or whatever, so it will generate false positives. Be +careful not change text like "this was fixed in 5.10.0"! Then run: $ Porting/bump-perl-version -u < /tmp/scan @@ -273,20 +287,24 @@ which will update all the files shown; then commit the changes. Be particularly careful with F, which contains a mixture of C<5.10.0>-type strings, some of which need bumping on every release, and -some of which need to be left. Also note that this tool currently only -performs a single change per line, so in particular, this line in -README.vms needs special handling: +some of which need to be left unchanged. Also note that this tool +currently only detects a single substitution per line: so in particular, +this line in README.vms needs special handling: rename perl-5^.10^.1.dir perl-5_10_1.dir =item * +I + Review and update INSTALL to account for the change in version number; in particular, the "Coexistence with earlier versions of perl 5" section. =item * +I + Update the F file to contain the git log command which would show all the changes in this release. You will need assume the existence of a not-yet created tag for the forthcoming release; e.g. @@ -296,134 +314,418 @@ not-yet created tag for the forthcoming release; e.g. Due to warts in the perforce-to-git migration, some branches require extra exclusions to avoid other branches being pulled in. Make sure you have the correct incantation: replace the not-yet-created tag with C and see -if git log produces roughly the right number of commits across roughly the -right time period. - +if C produces roughly the right number of commits across roughly the +right time period (you may find C useful). =item * -Check some more build configurations, e.g. +Check some more build configurations. The check that setuid builds and +installs is for < 5.11.0 only. - -Duseshrplib -Dd_dosuid - make suidperl + $ sh Configure -Dprefix=/tmp/perl-5.x.y -Uinstallusrbinperl \ + -Duseshrplib -Dd_dosuid + $ make + $ LD_LIBRARY_PATH=`pwd` make test # or similar for useshrplib -Check that setuid installs works (for < 5.11.0 only). -XXX any other configs? + $ make suidperl + $ su -c 'make install' + $ ls -l .../bin/sperl + -rws--x--x 1 root root 69974 2009-08-22 21:55 .../bin/sperl -=item * - -Make sure you have a PAUSE account suitable for uploading a perl release. -If you don't have a PAUSE account, then request one: - - https://pause.perl.org/pause/query?ACTION=request_id +(Then delete the installation directory.) -Check that your account is allowed to upload perl distros: goto -https://pause.perl.org/, login, then select 'upload file to CPAN'; there -should be a "For pumpkings only: Send a CC" tickbox. If not, ask Andreas -to add your ID to the list of people allowed to upload something called -perl. +XXX think of other configurations that need testing. =item * +I + Update F, using the C script, and if -necessary, update the script to include new alias mappings. +necessary, update the script to include new alias mappings for porters +already in F -XXX This script is currently broken (7/2009). It needs updating to work -with git and a lack of Changes files. + $ git log | perl Porting/checkAUTHORS.pl --acknowledged AUTHORS - =back -=head2 Building a release candidate +=head2 Building a release - on the day -(At this point you should already have performed the actions described in -L.) You should review -that section to ensure that everything there has done, and to see whether -any of those actions (such as consistency checks) need to be repeated. +This section describes the actions required to make a release (or snapshot +etc) that are performed on the actual day. =over 4 =item * +Review all the items in the previous section, +L<"Building a release - advance actions"> to ensure they are all done and +up-to-date. + +=item * + +I + Re-read the perldelta to try to find any embarrassing typos and thinkos; -remove any C or C flags; and run through pod and spell -checkers. [XXX show how] +remove any C or C flags; update the "Known Problems" section +with any serious issues for which fixes are not going to happen now; and +run through pod and spell checkers, e.g. + + $ podchecker -warnings -warnings pod/perl5101delta.pod + $ spell pod/perl5101delta.pod + +Also, you may want to generate and view an HTML version of it to check +formatting, e.g. + + $ perl pod/pod2html pod/perl5101delta.pod > /tmp/perl5101delta.html =item * -Update patchlevel.h to add a C<-RC1>-or-whatever string; or, if this is a -final release, remove it. [ XXX how now?? see 34813 for old way ] +Make sure you have a gitwise-clean perl directory (no modified files, +unpushed commits etc): + + $ git status =item * -Update C. +If not already built, Configure and build perl so that you have a Makefile +and porting tools: + + $ ./Configure -Dusedevel -des && make + +=item * + +Check that files managed by F and friends are up to date. From +within your working directory: + + $ git status + $ make regen + $ make regen_perly + $ git status + +If any of the files managed by F have changed, then you should +re-make perl to check that it's okay, then commit the updated versions: + + $ git commit -a -m 'make regen; make regen_perly' + +=item * + +Rebuild META.yml: + + $ rm META.yml + $ make META.yml + $ git diff + +XXX it would be nice to make Porting/makemeta use regen_lib.pl +to get the same 'update the file if its changed' functionality +we get with 'make regen' etc. + +Commit META.yml if it has changed: + + $ git commit -m 'Update META.yml' META.yml + +=item * + +I + +Update C with module version data for the new release. Note that if this is a maint release, you should run the following actions -from the maint directory, but edit the C in I and -subsequently cherry-pick it. +from the maint directory, but commit the C changes in +I and subsequently cherry-pick it. + +F uses ftp.funet.fi to verify information about dual-lived +modules on CPAN. It can use a full, local CPAN mirror or fall back +to C or C to fetch only package metadata remotely. + +(If you'd prefer to have a full CPAN mirror, see +http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN) + +Then change to your perl checkout, and if necessary, + + $ make perl + +If this not the first update for this version, first edit +F to delete the existing +entries for this version from the C<%released> and C<%version> hashes: +they will have a key like C<5.010001> for 5.10.1. + +XXX the edit-in-place functionality of Porting/corelist.pl should +be fixed to handle this automatically. + +Then, If you have a local CPAN mirror, run: + + $ ./perl -Ilib Porting/corelist.pl ~/my-cpan-mirror + +Otherwise, run: -First, in order to update the C<%upstream> and C<%bug_tracker> hashes, -the C script requires you to have a local CPAN -mirror. See http://www.cpan.org/misc/cpan-faq.html#How_mirror_CPAN for -more details, but basically: + $ ./perl -Ilib Porting/corelist.pl cpan - $ mkdir ~/cpan-mirror - $ rsync -av --delete ftp.funet.fi::CPAN ~/cpan-mirror/ +This will chug for a while, possibly reporting various warnings about +badly-indexed CPABN modules unreltaed to the modules actually in core. +Assuming all goes well, it will update +F. -(and re-run the rsync each time you need it to be up-to-date). -[XXX this really needs fixing to not require a whole CPAN mirror] +Check that file over carefully: + + $ git diff ext/Module-CoreList/lib/Module/CoreList.pm If necessary, bump C<$VERSION> (there's no need to do this for every RC; in RC1, bump the version to a new clean number that will appear in the final release, and leave as-is for the later RCs and final). -Then do +Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> +entry, as that is likely to reflect the previous version number. + +In addition, if this is a final release (rather than a release candidate): + +=over 4 - $ cd ~/perl/root; make perl - $ ./perl -Ilib Porting/corelist.pl ~/cpan-mirror/ > /tmp/corelist +=item * -This creates a file that looks something like +Update this version's entry in the C<%released> hash with today's date. - 5.010001 => { - 'AnyDBM_File' => '1.00', - ... - }, +=item * - %upstream = ( - 'App::Prove' => undef, - ... - ); +Make sure that the script has correctly updated the C section - %bug_tracker = ( - 'App::Prove' => 'http://rt.cpan.org/...', - ... - ); +=back -Cut and paste these tables into F: the module -version list should be appended as the last entry in the C<%version> hash -(or replaced, if we've already added it for an earlier release candidate), -while the existing C<%upstream> and C<%bug_tracker> hashes should be -replaced with the new versions. +Finally, commit the new version of Module::CoreList: +(unless this is for maint; in which case commit it blead first, then +cherry-pick it back). -Edit the version number in the new C<< 'Module::CoreList' => 'X.YZ' >> -entry, as that is likely to reflect the previous version number. + $ git commit -m 'Update Module::CoreList for 5.x.y' ext/Module-CoreList/lib/Module/CoreList.pm + +=item * + +Check that the manifest is sorted and correct: + + $ make manisort + $ make distclean + $ perl Porting/manicheck + $ git status + +Commit MANIFEST if it has changed: + + $ git commit -m 'Update MANIFEST' MANIFEST + +=item * + +I + +Add an entry to F with the current date, e.g.: + + David 5.10.1-RC1 2009-Aug-06 + +Make sure that the correct pumpking is listed in the left-hand column, and +if this is the first release under the stewardship of a new pumpking, make +sure that his or her name is listed in the section entitled +C. + +Be sure to commit your changes: + + $ git commit -m 'add new release to perlhist' pod/perlhist.pod + +=item * + +I + +Update F to add a C<-RC1>-or-whatever string; or, if this is +a final release, remove it. For example: + + static const char * const local_patches[] = { + NULL + + ,"RC1" + PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ + +Be sure to commit your change: + + $ git commit -m 'bump version to RCnnn' patchlevel.h + +=item * + +Build perl, then make sure it passes its own test suite, and installs: + + $ git clean -xdf + $ ./Configure -des -Dprefix=/tmp/perl-5.x.y-pretest + + # or if it's an odd-numbered version: + $ ./Configure -des -Dusedevel -Dprefix=/tmp/perl-5.x.y-pretest + + $ make test install + +=item * + +Check that the output of C and +C are as expected, +especially as regards version numbers, patch and/or RC levels, and @INC +paths. Note that as they have been been built from a git working +directory, they will still identify themselves using git tags and +commits. + +Then delete the temporary installation. + +=item * + +If this is maint release, make sure F is saved and +committed. + +=item * + +Push all your recent commits: + + $ git push origin .... + +=item * + +Create a tarball. Use the C<-s> option to specify a suitable suffix for +the tarball and directory name: + + $ cd root/of/perl/tree + $ make distclean + $ git clean -xdf # make sure perl and git agree on files + $ git status # and there's nothing lying around + + $ perl Porting/makerel -b -s `git describe` # for a snapshot + $ perl Porting/makerel -b -s RC1 # for a release candidate + $ perl Porting/makerel -b # for a final release + +This creates the directory F<../perl-x.y.z-RC1> or similar, copies all +the MANIFEST files into it, sets the correct permissions on them, +adds DOS line endings to some, then tars it up as +F<../perl-x.y.z-RC1.tar.gz>. With C<-b>, it also creates a C file. + +XXX if we go for extra tags and branches stuff, then add the extra details +here + +=item * + +Clean up the temporary directory, e.g. + + $ rm -rf ../perl-x.y.z-RC1 + +=item * + +Copy the tarballs (.gz and possibly .bz2) to a web server somewhere you +have access to. + +=item * + +Download the tarball to some other machine. For a release candidate, +you really want to test your tarball on two or more different platforms +and architectures. The #p5p IRC channel on irc.perl.org is a good place +to find willing victims. + +=item * + +Check that basic configuration and tests work on each test machine: + + $ ./Configure -des && make all test + +=item * + +Check that the test harness and install work on each test machine: + + $ make distclean + $ ./Configure -des -Dprefix=/install/path && make all test_harness install + $ cd /install/path + +=item * + +Check that the output of C and C are as expected, +especially as regards version numbers, patch and/or RC levels, and @INC +paths. + +Note that the results may be different without a F<.git/> directory, +which is why you should test from the tarball. + +=item * + +Run the Installation Verification Procedure utility: + + $ bin/perlivp + ... + All tests successful. + $ + +=item * + +Compare the pathnames of all installed files with those of the previous +release (i.e. against the last installed tarball on this branch which you +have previously verified using this same procedure). In particular, look +for files in the wrong place, or files no longer included which should be. +For example, suppose the about-to-be-released version is 5.10.1 and the +previous is 5.10.0: + + cd installdir-5.10.0/ + find . -type f | perl -pe's/5\.10\.0/5.10.1/g' | sort > /tmp/f1 + cd installdir-5.10.1/ + find . -type f | sort > /tmp/f2 + diff -u /tmp/f[12] + +=item * + +Bootstrap the CPAN client on the clean install: + + $ bin/perl -MCPAN -e'shell' + +=item * + +Try installing a popular CPAN module that's reasonably complex and that +has dependencies; for example: -Then, add the current perl version to the C paragraph. + CPAN> install Inline + CPAN> quit -Add or update an entry to the C<%released> hash, including today's date -(if this is just a release candidate, set the date to '????-??-??'). +Check that your perl can run this: + $ bin/perl -lwe 'use Inline C => "int f() { return 42;} "; print f' + 42 + $ =item * -Follow the instructions in the section L, then -carry on with the extra steps that follow here. +Bootstrap the CPANPLUS client on the clean install: + + $ bin/cpanp + +=item * + +Install an XS module, for example: + + CPAN Terminal> i DBI + CPAN Terminal> quit + $ bin/perl -MDBI -e 1 + $ =item * -Disarm the patchlevel.h change [ XXX expand ] +I + +Check that the C utility works. Try the following: + + $ bin/perlbug + ... + Subject: test bug report + Local perl administrator [yourself]: + Editor [vi]: + Module: + Category [core]: + Severity [low]: + (edit report) + Action (Send/Display/Edit/Subject/Save to File): f + Name of file to save message in [perlbug.rep]: + Action (Send/Display/Edit/Subject/Save to File): q + +and carefully examine the output (in F), especially +the "Locally applied patches" section. If everything appears okay, then +delete the file, and try it again, this time actually submitting the bug +report. Check that it shows up, then remember to close it! =item * +I + Wait for the smoke tests to catch up with the commit which this release is based on (or at least the last commit of any consequence). @@ -433,125 +735,188 @@ back and fix things. =item * +I + Once smoking is okay, upload it to PAUSE. This is the point of no return. -You may wish to create a .bz2 version of the tarball and upload that too. +If anything goes wrong after this point, you will need to re-prepare +a new release with a new minor version or RC number. + + https://pause.perl.org/ + +(Login, then select 'Upload a file to CPAN') + +Upload both the .gz and .bz2 versions of the tarball. =item * -create a tag [XXX and branches and stuff ????], e.g.: +I - $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' +Create a tag for the exact git revision you built the release from. +C below is the commit corresponding to the tarball. It can be +omitted if there have been no further commits since the tarball was +created, for example: + + $ git tag perl-5.10.1-RC1 -m'Release Candidate 1 of Perl 5.10.1' $ git push origin tag perl-5.10.1-RC1 =item * -Mail p5p to announce it, with a quote you prepared earlier. +I + +Disarm the F change; for example, + + static const char * const local_patches[] = { + NULL + - ,"RC1" + PERL_GIT_UNPUSHED_COMMITS /* do not remove this line */ + +Be sure to commit your change: + + $ git commit -m 'disarm RCnnn bump' patchlevel.h + $ git push origin .... + =item * +Mail p5p to announce your new release, with a quote you prepared earlier. + +=item * + +I + Wait 24 hours or so, then post the announcement to use.perl.org. (if you don't have access rights to post news, ask someone like Rafael to do it for you.) -=back +=item * +I -=head2 Making a final release +Ask Jarkko to add the tarball to http://www.cpan.org/src/ -At this point you should have a working release candidate with few or no -changes since. +=item * -It's essentially the same procedure as for making a release candidate, but -with a whole bunch of extra post-release steps. +I -=over 4 +Ask Jarkko to update the descriptions of which tarballs are current in +http://www.cpan.org/src/README.html, and Rafael to update +http://dev.perl.org/perl5/ =item * -Follow the same steps as for making a release candidate, then +I + +Remind the current maintainer of C to push a new release +to CPAN. =item * -Ask Jarkko to update http://www.cpan.org/src/README.html and -Rafael to update http://dev.perl.org/perl5/ +I -=item * +Bump the perlXYZ version number. -Create a new empty perlNNNdelta.pod file for the current release + 1; +First, create a new empty perlNNNdelta.pod file for the current release + 1; see F. -[ XXX Perhaps we should have an empty template file we can copy in. ] -In addition, edit F, adding the new entry as 'D', and unmark previous -entry as 'D', then run C to update the -following files: +You should be able to do this by just copying in a skeleton template and +then doing a quick fix up of the version numbers, e.g. + + $ cp -i Porting/perldelta_template pod/perl5102delta.pod + $ (edit it) + $ git add pod/perl5102delta.pod + +Edit F: add the new entry, flagged as 'D', and unflag the previous +entry from being 'D'; for example: + + -D perl5101delta Perl changes in version 5.10.1 + +D perl5102delta Perl changes in version 5.10.2 + + perl5101delta Perl changes in version 5.10.1 + +Run C to update the F version in +the following files: MANIFEST + Makefile.SH + pod.lst pod/perl.pod - win32/pod.mak vms/descrip_mms.template + win32/Makefile + win32/makefile.mk + win32/pod.mak -(F still needs a manual edit to bump the -C entry - it would be good for someone to figure out the fix.) +Then manually edit (F to bump the version +in the following entry: -and change perlNNNdelta references to the new version in these files + [.pod]perldelta.pod : [.pod]perl5101delta.pod + +XXX this previous step needs to fixed to automate it in pod/buildtoc. + +Manually update references to the perlNNNdelta version in these files: INSTALL - win32/Makefile.mk - win32/Makefile - Makefile.SH README -Also, edit the previous delta file to change the C from C +Edit the previous delta file to change the C from C to C. These two lists of files probably aren't exhaustive; do a recursive grep -on the previous filename to look for suitable candidates. +on the previous filename to look for suitable candidates that may have +been missed. -(see 16410843ea for an example). +Finally, commit: -=item * - -If this was a maintenance release, then edit F to change -all the C (deferred) flags to C<.> (needs review). + $ git commit -a -m 'create perlXXXdelta' +At this point you may want to compare the commit with a previous bump to +see if they look similar. See commit ca8de22071 for an example of a +previous version bump. =item * -If this was a major release, then +I -=over +If this was a maint release, then edit F to change +all the C (deferred) flags to C<.> (needs review). =item * -bump the version, e.g. 5.12.0 to 5.13.0; +I -=item * +If this was a major release (5.x.0), then create a new maint branch +based on the commit tagged as the current release and bump the version +in the blead branch in git, e.g. 5.12.0 to 5.13.0. [ XXX probably lots more stuff to do, including perldelta, C ] +XXX need a git recipe + =item * -Create a new maint branch with an empty Porting/mergelog file -[ XXX and lots of other stuff too, probably ] +I -=back +Copy the perlNNNdelta.pod for this release into the other branches; for +example: -=item * + $ cp -i ../5.10.x/pod/perl5101delta.pod pod/ # for example + $ git add pod/perl5101delta.pod -Copy the perlNNNdelta.pod for this release into the other branches, and -remember to update these files on those branches too: +Edit F to add an entry for the file, e.g.: - MANIFEST - pod.lst - pod/perl.pod - vms/descrip_mms.template - win32/pod.mak + perl5101delta Perl changes in version 5.10.1 + +Then rebuild various files: + + $ perl pod/buildtoc --build-all + +Finally, commit: -(see fc5be80860 for an example). + $ git commit -a -m 'add perlXXXdelta' =item * +I + Make sure any recent F entries are copied to F on other branches; typically the RC* and final entries, e.g. @@ -562,8 +927,10 @@ e.g. =item * -Remind the current maintainer of C to push a new release -to CPAN. +I. + +Thanks for releasing perl! =back