Skip to content

More release manager guide edits #23770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 28, 2025
Merged

More release manager guide edits #23770

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6f24468
RMG: Make it linear for Bump the version number taking advantage of m…
thibaultduponchelle Sep 26, 2025
c3ae113
RMG: Better git tag with replaced version number
thibaultduponchelle Sep 26, 2025
14b1a95
RMG: More code in code block (ready to copy-paste)
thibaultduponchelle Sep 26, 2025
effe7c9
RMG: You MUST SKIP is totally redundant with make-rmg-checklist. And …
thibaultduponchelle Sep 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 81 additions & 37 deletions Porting/release_managers_guide.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,10 +483,9 @@ You won't be able to automatically fill in the "Updated Modules" section until
after L<Module::CoreList> is updated (as described below in
L</"Update Module::CoreList">).

=head3 Bump the version number
=for checklist skip BLEAD-POINT
Copy link
Contributor

@ericherman ericherman Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a very good improvement.


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).

Expand Down Expand Up @@ -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<Porting/updateAUTHORS.pl>.
The AUTHORS file can be updated by running:

$ perl Porting/updateAUTHORS.pl
Copy link
Contributor

@book book Sep 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personal preference, but I think that 4 spaces stand out more for verbatim test. It's also consistent with Markdown syntax.

Copy link
Member Author

@thibaultduponchelle thibaultduponchelle Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost all other verbatim are standing out 1 space.

Copy link
Contributor

@khwilliamson khwilliamson Sep 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe in 1 space verbatim. My vim editor shows it in a different color, making it stand out, without needing extra indentation; I presume other editors do the same. I just looked at blead's RMG using less, and it seemed fine to me.

The real reason to use 1 space indents is to minimize wrapping of lines too long to fit in the terminal width. When this happens it is ugly and hard to read, a far worse outcome in my opinion than indenting fewer spaces. A one-space indent means we've tried our best to keep this from happening, no matter what the terminal width, except if we were to split the line into multiple ones. Sometimes that might be advisable, but in many instances it would make things actually harder for the reader.

The minimum terminal width we claim to try to cater to is 80 columns.

I've encountered more than a few instances where I've added verbatim text that is 80ish columns wide, but will wrap under the prevailing 4 space indent existing in the file. I think it is inconsiderate to future readers to just let it wrap, or to expect that everyone is using a wider terminal width than 80. It's better to make it fit, which means decreasing the indent. But then, this line will not conform to the rest of the file. Do I change the rest of the file at this time? It would be better for that file to have contained a 1-space indent from the beginning. I don't think existing files should be changed because of this prospect, but I do think that any new file should use 1 space verbatim indents.


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
Expand Down Expand Up @@ -927,8 +929,6 @@ Be sure to commit your changes:

=head3 Update patchlevel.h

I<You MUST SKIP this step for a BLEAD-POINT release>

Update F<patchlevel.h> to add a C<-RC1>-or-whatever string; or, if this is
a final release, remove it. For example:

Expand Down Expand Up @@ -981,9 +981,9 @@ Then delete the temporary installation.

=head3 Create the release tag

Create the I<annotated> tag identifying this release (e.g.):
Create the I<annotated> 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<VERY> important that from this point forward, you not push
your git changes to the Perl master repository. If anything goes
Expand Down Expand Up @@ -1171,7 +1171,7 @@ Test L<perlbug> 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<perlbug.rep]>), especially
Then carefully examine the output (in F<perlbug.rep]>), especially
the "Locally applied patches" section.

=for checklist skip BLEAD-POINT
Expand Down Expand Up @@ -1239,8 +1239,6 @@ which may be faster.

=head3 Wait for indexing

I<You MUST SKIP this step for RC and BLEAD-POINT>

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.
Expand All @@ -1250,8 +1248,6 @@ This is considered normal.

=head3 Disarm patchlevel.h

I<You MUST SKIP this step for BLEAD-POINT release>

Disarm the F<patchlevel.h> change; for example,

static const char * const local_patches[] = {
Expand Down Expand Up @@ -1318,25 +1314,19 @@ release, update F<docs/shared/tpl/stats.html>.

=head3 Release schedule

I<You MUST SKIP this step for RC>

Tick the entry for your release in F<Porting/release_schedule.pod>.

=for checklist skip RC

=head3 Module::CoreList nagging

I<You MUST SKIP this step for RC>

Remind the current maintainer of C<Module::CoreList> to push a new release
to CPAN.

=for checklist skip RC

=head3 New perldelta

I<You MUST SKIP this step for RC>

Create a new perldelta.

=over 4
Expand All @@ -1348,21 +1338,33 @@ Confirm that you have a clean checkout with no local changes.
=item *

Run:
perl Porting/new-perldelta.pl

$ perl Porting/new-perldelta.pl

=item *

Run the C<git add> commands it outputs to add new and modified files.

=item *

Verify that the build still works, by running C<./Configure> and
C<make test_porting>. (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<t/porting/podcheck.t> spots errors in the new F<pod/perldelta.pod>,
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<pod/perldelta.pod>, 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 *
Expand All @@ -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<You MUST SKIP this step for RC and MAINT>
=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
Expand All @@ -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<regen/feature.pl> to propagate the changes to F<lib/feature.pm>.
Run:

Then follow the section L</"Bump the version number"> 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</"Bump the version number">.
It will propagate the changes to F<lib/feature.pm>.

After bumping the version, follow the section L</"Update INSTALL"> to
ensure all version number references are correct.
Expand All @@ -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<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.
See below in L</"Update INSTALL"> 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</"Update Module::CoreList">) 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
Expand Down Expand Up @@ -1464,8 +1512,6 @@ Finally, push any commits done above.

=head3 Create maint branch

I<You MUST SKIP this step for RC, BLEAD-POINT, MAINT>

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.
Expand All @@ -1479,8 +1525,6 @@ Assuming you're using git 1.7.x or newer:

=head3 Copy perldelta.pod to blead

I<You MUST SKIP this step for RC, BLEAD-POINT>

Copy the perldelta.pod for this release into blead; for example:

$ cd ..../blead
Expand Down
Loading