diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod index 76d291bea255..e7db37246950 100644 --- a/Porting/release_managers_guide.pod +++ b/Porting/release_managers_guide.pod @@ -483,10 +483,9 @@ You won't be able to automatically fill in the "Updated Modules" section until after L is updated (as described below in L). -=head3 Bump the version number +=for checklist skip BLEAD-POINT -Do not do this yet for a BLEAD-POINT release! You will do this at the end of -the release process (after building the final tarball, tagging etc). +=head3 Bump the version number Increase the version number (e.g. from 5.12.0 to 5.12.1). @@ -578,7 +577,10 @@ blead release, so you may find nothing to do here. =head3 Update AUTHORS -The AUTHORS file can be updated by running F. +The AUTHORS file can be updated by running: + + $ perl Porting/updateAUTHORS.pl + This shouldn't really be necessary anymore, and in theory nothing should change as our CI should not pass if a commit would result in AUTHORS needing to change, but do it anyway to be sure. Make sure all your changes @@ -927,8 +929,6 @@ Be sure to commit your changes: =head3 Update patchlevel.h -I - Update F to add a C<-RC1>-or-whatever string; or, if this is a final release, remove it. For example: @@ -981,9 +981,9 @@ Then delete the temporary installation. =head3 Create the release tag -Create the I tag identifying this release (e.g.): +Create the I tag identifying this release: - $ git tag v5.21.4 -m 'Perl 5.21.4' + $ git tag v5.X.Y -m 'Perl 5.X.Y' It is B important that from this point forward, you not push your git changes to the Perl master repository. If anything goes @@ -1171,7 +1171,7 @@ Test L with the following: Action (Send/Display/Edit/Subject/Save to File): f Name of file to save message in [perlbug.rep]: -and carefully examine the output (in F), especially +Then carefully examine the output (in F), especially the "Locally applied patches" section. =for checklist skip BLEAD-POINT @@ -1239,8 +1239,6 @@ which may be faster. =head3 Wait for indexing -I - Wait until you receive notification emails from the PAUSE indexer confirming that your uploads have been received. IMPORTANT -- you will probably get an email that indexing has failed, due to module permissions. @@ -1250,8 +1248,6 @@ This is considered normal. =head3 Disarm patchlevel.h -I - Disarm the F change; for example, static const char * const local_patches[] = { @@ -1318,16 +1314,12 @@ release, update F. =head3 Release schedule -I - Tick the entry for your release in F. =for checklist skip RC =head3 Module::CoreList nagging -I - Remind the current maintainer of C to push a new release to CPAN. @@ -1335,8 +1327,6 @@ to CPAN. =head3 New perldelta -I - Create a new perldelta. =over 4 @@ -1348,7 +1338,8 @@ Confirm that you have a clean checkout with no local changes. =item * Run: - perl Porting/new-perldelta.pl + + $ perl Porting/new-perldelta.pl =item * @@ -1356,13 +1347,24 @@ Run the C commands it outputs to add new and modified files. =item * -Verify that the build still works, by running C<./Configure> and -C. (On Win32 use the appropriate make utility). +Verify that the build still works, by running: + + $ ./Configure + $ make test_porting + +(On Win32 use the appropriate make utility). =item * -If F spots errors in the new F, -run C<./perl -MTestInit t/porting/podcheck.t | less> for more detail. +Run: + + $ ./perl t/porting/podcheck.t + +If it spots errors in the new F, run: + + $ ./perl -MTestInit t/porting/podcheck.t | less + +It will give you more details. Skip to the end of its test output to see the options it offers you. =item * @@ -1377,11 +1379,9 @@ At this point you may want to compare the commit with a previous bump to see if they look similar. See commit ba03bc34a4 for an example of a previous version bump. -=for checklist skip MAINT RC - -=head3 Bump version +=for checklist skip BLEAD-POINT RC MAINT -I +=head3 Bump the feature bundles If this was a BLEAD-FINAL release (i.e. the first release of a new maint series, 5.x.0 where x is even), then bump the version in the blead branch @@ -1394,13 +1394,11 @@ marker); e.g. "5.14" => [qw(switch say state unicode_strings)], + "5.15" => [qw(switch say state unicode_strings)], -Run F to propagate the changes to F. +Run: -Then follow the section L to bump the version -in the remaining files and test and commit. + $ ./perl regen/feature.pl -If this was a BLEAD-POINT release, then just follow the section -L. +It will propagate the changes to F. After bumping the version, follow the section L to ensure all version number references are correct. @@ -1417,6 +1415,56 @@ reports to arise. (The opposite problem -- trying to figure out why there introduced later -- shouldn't arise for MAINT releases since they should, in theory, only contain bug fixes but never regressions.)) +=for checklist skip RC MAINT + +=head3 Bump the version number + +Increase the version number (e.g. from 5.12.0 to 5.12.1). + +There is a tool to semi-automate this process: + + $ ./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 +"this was fixed in 5.10.0"! + +Use git status and git diff to select changes you want to keep. + +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 unchanged. +See below in L for more details. + +After editing, you may need to regen opcodes: + + $ ./perl -Ilib regen/opcode.pl + +Test your changes: + + $ git clean -xdf # careful if you don't have local files to keep! + $ ./Configure -des -Dusedevel + $ make + $ make test + +Do note that at this stage, porting tests will fail. They will continue +to fail until you've updated Module::CoreList, as described below. + +Commit your changes: + + $ git status + $ git diff + # Review the delta carefully + $ 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 +previous version bump. + +When the version number is bumped, you should also update Module::CoreList +(as described in L) to reflect the new +version number. + =head3 Clean build and test Run a clean build and test to make sure nothing obvious is broken. This is @@ -1464,8 +1512,6 @@ Finally, push any commits done above. =head3 Create maint branch -I - If this was a BLEAD-FINAL release (i.e. the first release of a new maint series, 5.x.0 where x is even), then create a new maint branch based on the commit tagged as the current release. @@ -1479,8 +1525,6 @@ Assuming you're using git 1.7.x or newer: =head3 Copy perldelta.pod to blead -I - Copy the perldelta.pod for this release into blead; for example: $ cd ..../blead