In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/2f05d2097c6cf5e9fa8a7473b06bc8c21aeb9044?hp=04ce8649990a4784cc3ad0b83a45ccf6a005b1be>
- Log ----------------------------------------------------------------- commit 2f05d2097c6cf5e9fa8a7473b06bc8c21aeb9044 Author: Steve Hay <[email protected]> Date: Sat Jan 31 15:19:40 2015 +0000 RMG - Put all version-bump related information about INSTALL in one place Also correct the phrase referred to by the RMG to match what INSTALL actualy says, and change the wording of one section of INSTALL to match the other. M INSTALL M Porting/release_managers_guide.pod commit 78a6230914951e5879c967c6dc849b747a0f9c72 Author: Steve Hay <[email protected]> Date: Sat Jan 31 14:57:09 2015 +0000 RMG - Consistent four-space indent; wrap all lines to 79 characters M Porting/release_managers_guide.pod commit a4a5107a70398a345859cc5ea0ec382b6ecdc9f3 Author: Steve Hay <[email protected]> Date: Sat Jan 31 13:48:10 2015 +0000 RMG - Module/CoreList.pod is no longer updated, since 64eeb2c06c M Porting/release_managers_guide.pod commit be2822b05a2917d75353f93b9331bb7bb06a63eb Author: Steve Hay <[email protected]> Date: Sat Jan 31 13:43:32 2015 +0000 RMG - Show correct Porting/corelist-perldelta.pl command for MAINT releases M Porting/release_managers_guide.pod ----------------------------------------------------------------------- Summary of changes: INSTALL | 2 +- Porting/release_managers_guide.pod | 151 +++++++++++++++++++------------------ 2 files changed, 79 insertions(+), 74 deletions(-) diff --git a/INSTALL b/INSTALL index 7fa0701..e2c7a10 100644 --- a/INSTALL +++ b/INSTALL @@ -89,7 +89,7 @@ potential incompatibilities introduced with this release. A few of the most important issues are listed below, but you should refer to pod/perldelta.pod for more detailed information. -B<WARNING:> This version is not binary compatible with prior releases of Perl. +B<WARNING:> This version is not binary compatible with earlier versions of Perl. If you have built extensions (i.e. modules that include C code) using an earlier version of Perl, you will need to rebuild and reinstall those extensions. diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod index 76e0f45..1a503b3 100644 --- a/Porting/release_managers_guide.pod +++ b/Porting/release_managers_guide.pod @@ -15,14 +15,14 @@ document that starts with a checklist for your release. This script is run as: - perl Porting/make-rmg-checklist \ - --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod + perl Porting/make-rmg-checklist \ + --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.pod You can also pass the C<--html> flag to generate an HTML document instead of POD. - perl Porting/make-rmg-checklist --html \ - --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html + perl Porting/make-rmg-checklist --html \ + --type [BLEAD-POINT or MAINT or ...] > /tmp/rmg.html =head1 SYNOPSIS @@ -321,23 +321,23 @@ C<nmake> instead. Ensure dual-life CPAN modules are stable, which comes down to: - for each module that fails its regression tests on $current - did it fail identically on $previous? - if yes, "SEP" (Somebody Else's Problem) - else work out why it failed (a bisect is useful for this) + for each module that fails its regression tests on $current + did it fail identically on $previous? + if yes, "SEP" (Somebody Else's Problem) + else work out why it failed (a bisect is useful for this) - attempt to group failure causes + attempt to group failure causes - for each failure cause - is that a regression? - if yes, figure out how to fix it - (more code? revert the code that broke it) - else - (presumably) it's relying on something un-or-under-documented - should the existing behaviour stay? - yes - goto "regression" - no - note it in perldelta as a significant bugfix - (also, try to inform the module's author) + for each failure cause + is that a regression? + if yes, figure out how to fix it + (more code? revert the code that broke it) + else + (presumably) it's relying on something un-or-under-documented + should the existing behaviour stay? + yes - goto "regression" + no - note it in perldelta as a significant bugfix + (also, try to inform the module's author) =head3 monitor smoke tests for failures @@ -377,7 +377,7 @@ bump the version further. There is a tool to semi-automate this process: - $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1 + $ ./perl -Ilib Porting/bump-perl-version -i 5.10.0 5.10.1 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 @@ -388,8 +388,7 @@ Use git status and git diff to select changes you want to keep. Be particularly careful with F<INSTALL>, 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 unchanged. -The line in F<INSTALL> about "is binary incompatible with" requires a -correct choice of earlier version to declare incompatibility with. +See below in L<"update INSTALL"> for more details. For the first RC release leading up to a BLEAD-FINAL release, update the description of which releases are now "officially" supported in @@ -405,13 +404,13 @@ to guarantee binary compatibility in maint branches. After editing, regenerate uconfig.h (this must be run on a system with a /bin/sh available): - $ perl regen/uconfig_h.pl + $ perl regen/uconfig_h.pl This might not cause any new changes. You may also need to regen opcodes: - $ ./perl -Ilib regen/opcode.pl + $ ./perl -Ilib regen/opcode.pl You may have to add stub entries in C<%Module::CoreList::version>, C<%Module::CoreList::deprecated> and C<%Module::CoreList::Utils::delta>. @@ -419,18 +418,18 @@ If so, you must up their version numbers as well. Test your changes: - $ git clean -xdf # careful if you don't have local files to keep! - $ ./Configure -des -Dusedevel - $ make - $ make test + $ git clean -xdf # careful if you don't have local files to keep! + $ ./Configure -des -Dusedevel + $ make + $ make test Commit your changes: - $ git status - $ git diff - B<review the delta carefully> + $ git status + $ git diff + B<review the delta carefully> - $ git commit -a -m 'Bump the perl version in various places for 5.x.y' + $ git commit -a -m 'Bump the perl version in various places for 5.x.y' At this point you may want to compare the commit with a previous bump to see if they look similar. See commit f7cf42bb69 for an example of a @@ -442,8 +441,11 @@ version number. =head3 update INSTALL -Review and update INSTALL to account for the change in version number; -in particular, the "Coexistence with earlier versions of perl 5" section. +Review and update INSTALL to account for the change in version number. +The lines in F<INSTALL> about "is not binary compatible with" may require a +correct choice of earlier version to declare incompatibility with. These are +in the "Changes and Incompatibilities" and "Coexistence with earlier versions +of perl 5" sections. Be particularly careful with the section "Upgrading from 5.X.Y or earlier". The "X.Y" needs to be changed to the most recent version that we are @@ -460,7 +462,7 @@ release (so for 5.15.3 this would be 5.15.2). Check that the copyright years are up to date by running: - $ ./perl t/porting/copyright.t --now + $ ./perl t/porting/copyright.t --now Remedy any test failures by editing README or perl.c accordingly (search for the "Copyright"). If updating perl.c, check if the file's own copyright date in @@ -521,7 +523,7 @@ need to freeze blead during the release. This is less important for BLEAD-FINAL, MAINT, and RC releases, since blead will already be frozen in those cases. Create the branch by running - git checkout -b release-5.xx.yy + git checkout -b release-5.xx.yy =head3 build a clean perl @@ -553,8 +555,8 @@ maintainer for 'cpan' upstream modules. =head4 Bump Module::CoreList* $VERSIONs -If necessary, bump C<$Module::CoreList::VERSION> (there's no need to do this for -every RC; in RC1, bump the version to a new clean number that will +If necessary, bump C<$Module::CoreList::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). It may also happen that C<Module::CoreList> has been modified in blead, and hence has a new version number already. (But make sure it is not the same @@ -613,13 +615,11 @@ This will chug for a while, possibly reporting various warnings about badly-indexed CPAN modules unrelated to the modules actually in core. Assuming all goes well, it will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and possibly -F<dist/Module-CoreList/lib/Module/CoreList.pod> and/or F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm>. Check those files over carefully: $ git diff dist/Module-CoreList/lib/Module/CoreList.pm - $ git diff dist/Module-CoreList/lib/Module/CoreList.pod $ git diff dist/Module-CoreList/lib/Module/CoreList/Utils.pm =head4 Bump version in Module::CoreList F<Changes> @@ -642,12 +642,6 @@ For any release except an RC: Update this version's entry in the C<%released> hash with today's date. -=item * - -Make sure that the script has correctly updated the C<CAVEATS> section -(Note, the C<CAVEATS> section is in -F<dist/Module-CoreList/lib/Module/CoreList.pod>) - =back =head4 Commit Module::CoreList changes @@ -656,23 +650,33 @@ Finally, commit the new version of Module::CoreList: (unless this is for MAINT; in which case commit it to blead first, then cherry-pick it back). - $ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/Changes dist/Module-CoreList/lib/Module/CoreList.pm dist/Module-CoreList/lib/Module/CoreList.pod dist/Module-CoreList/lib/ ... [24 chars truncated] + $ git commit -m 'Update Module::CoreList for 5.x.y' \ + dist/Module-CoreList/Changes \ + dist/Module-CoreList/lib/Module/CoreList.pm \ + dist/Module-CoreList/lib/Module/CoreList/Utils.pm =head4 Rebuild and test -Build and test to get the changes into the currently built lib directory and to ensure -all tests are passing. +Build and test to get the changes into the currently built lib directory and to +ensure all tests are passing. =head3 finalize perldelta Finalize the perldelta. In particular, fill in the Acknowledgements section, which can be generated with something like: - $ perl Porting/acknowledgements.pl v5.15.0..HEAD + $ perl Porting/acknowledgements.pl v5.15.0..HEAD + +Fill in the "New/Updated Modules" sections now that Module::CoreList is +updated: + + $ ./perl -Ilib Porting/corelist-perldelta.pl \ + --mode=update pod/perldelta.pod -Fill in the "New/Updated Modules" sections now that Module::CoreList is updated: +For a MAINT release use something like this instead: - $ ./perl -Ilib Porting/corelist-perldelta.pl --mode=update pod/perldelta.pod + $ ./perl -Ilib Porting/corelist-perldelta.pl 5.020001 5.020002 \ + --mode=update pod/perldelta.pod Ideally, also fill in a summary of the major changes to each module for which an entry has been added by F<corelist-perldelta.pl>. @@ -688,7 +692,8 @@ run through pod and spell checkers, e.g. Also, you may want to generate and view an HTML version of it to check formatting, e.g. - $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > /tmp/perldelta.html + $ ./perl -Ilib ext/Pod-Html/bin/pod2html pod/perldelta.pod > \ + /tmp/perldelta.html Another good HTML preview option is http://search.cpan.org/pod2html @@ -834,7 +839,7 @@ directory, they will still identify themselves using git tags and commits. (Note that for an odd-numbered version, perl will install itself as C<perl5.x.y>). C<perl -v> will identify itself as: - This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef)) + This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef)) where 5.X.Z is the latest tag, NNN the number of commits since this tag, and C<< deadbeef >> commit of that tag. @@ -873,14 +878,14 @@ L<http://tukaani.org/xz/>. 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 # make sure distclean works - $ git clean -xdf # make sure perl and git agree on files - # git clean should not output anything! - $ git status # and there's nothing lying around + $ cd root/of/perl/tree + $ make distclean # make sure distclean works + $ git clean -xdf # make sure perl and git agree on files + # git clean should not output anything! + $ git status # and there's nothing lying around - $ perl Porting/makerel -bx -s RC1 # for a release candidate - $ perl Porting/makerel -bx # for a final release + $ perl Porting/makerel -bx -s RC1 # for a release candidate + $ perl Porting/makerel -bx # 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, then @@ -1096,11 +1101,11 @@ Send a carbon copy to C<[email protected]> Merge the (local) release branch back into master now, and delete it. - git checkout blead - git pull - git merge release-5.xx.yy - git push - git branch -d release-5.xx.yy + git checkout blead + git pull + git merge release-5.xx.yy + git push + git branch -d release-5.xx.yy Note: The merge will create a merge commit if other changes have been pushed to blead while you've been working on your release branch. Do NOT rebase your @@ -1303,9 +1308,9 @@ I<You MUST SKIP this step for RC, BLEAD-POINT> Copy the perldelta.pod for this release into blead; for example: - $ cd ..../blead - $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example - $ git add pod/perl5101delta.pod + $ cd ..../blead + $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example + $ git add pod/perl5101delta.pod Don't forget to set the NAME correctly in the new file (e.g. perl5101delta rather than perldelta). @@ -1330,7 +1335,7 @@ Finally, commit and push: Make sure any recent F<pod/perlhist.pod> entries are copied to F<perlhist.pod> on blead. e.g. - 5.8.9 2008-Dec-14 + 5.8.9 2008-Dec-14 =head3 bump RT version number @@ -1386,8 +1391,7 @@ Otherwise, run: $ ./perl -Ilib Porting/corelist.pl cpan -This will update F<dist/Module-CoreList/lib/Module/CoreList.pm>, -F<dist/Module-CoreList/lib/Module/CoreList.pod> and +This will update F<dist/Module-CoreList/lib/Module/CoreList.pm> and F<dist/Module-CoreList/lib/Module/CoreList/Utils.pm> as it did before, but this time adding new sections for the next BLEAD-POINT release. @@ -1410,7 +1414,8 @@ test_porting makefile target to check that they're ok. Run - $ ./perl -Ilib -MModule::CoreList -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"' + $ ./perl -Ilib -MModule::CoreList \ + -le 'print Module::CoreList->find_version($]) ? "ok" : "not ok"' and check that it outputs "ok" to prove that Module::CoreList now knows about blead's current version. -- Perl5 Master Repository
