Also, you may want to generate and view an HTML version of it to check
formatting, e.g.
- $ ./perl -Ilib ext/Pod-Html/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
If you make changes, be sure to commit them.
+=head3 remove stale perldeltas
+
+For the first RC release that is ONLY for a BLEAD-FINAL, the perldeltas
+from the BLEAD-POINT releases since the previous BLEAD_FINAL should have
+now been consolidated into the current perldelta, and hence are now just
+useless clutter. They can be removed using:
+
+ $ git rm <file1> <file2> ...
+
+For example, for RC0 of 5.16.0:
+
+ $ cd pod
+ $ git rm perldelta515*.pod
+
+All mention to them should also be removed. Currently the files that
+need to be edited for this task are F<MANIFEST>, F<pod.list>,
+F<pod/perl.pod>, and F<win32/pod.mak> (including C<.man>, C<.html>, and
+C<.tex> entries for each removed pod).
+
+Then build a clean perl and do a full test
+
+ $ git status
+ $ git clean -dxf
+ $ ./Configure -Dusedevel -des
+ $ make
+ $ make test
+
+Once all tests pass, commit your changes.
=head3 build a clean perl
-Make sure you have a gitwise-clean perl directory (no modified files,
+If you skipped the previous step (removing the stale perldeltas)
+make sure you have a gitwise-clean perl directory (no modified files,
unpushed commits etc):
$ git status
$ ./Configure -Dusedevel -des && make
-
=head3 update Module::CoreList
Update C<Module::CoreList> with module version data for the new release.
$ make
-If this not the first update for this version (e.g. if it was updated
+If this is not the first update for this version (e.g. if it was updated
when the version number was originally bumped), first edit
F<dist/Module-CoreList/lib/Module/CoreList.pm> to delete the existing
entries for this version from the C<%released> and C<%version> hashes:
$ git commit -m 'Update Module::CoreList for 5.x.y' dist/Module-CoreList/lib/Module/CoreList.pm
-=head3 check MANIFEST
-
-Check that the manifest is sorted and correct:
-
- $ make distclean
- $ git clean -xdf # This shouldn't be necessary if distclean is correct
- $ perl Porting/manicheck
-
-If manicheck turns up anything wrong, update MANIFEST and begin this step again.
-
- $ ./configure -des -Dusedevel
- $ make test_porting
- $ git commit -m 'Update MANIFEST' MANIFEST
-
-
=head3 update perlhist.pod
I<You MUST SKIP this step for a RC release>
Upload both the .gz and .bz2 versions of the tarball.
-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.
-This is considered normal.
-
Do not proceed any further until you are sure that your tarballs are on
CPAN. Check your authors directory on one of the "fast" CPAN mirrors
(e.g., cpan.hexten.net
or cpan.cpantesters.org) to confirm that your uploads have been successful.
+I<You MUST SKIP this step for RC>
+
+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.
+This is considered normal.
+
=head3 publish tag
Mail p5p to announce your new release, with a quote you prepared earlier.
+Use the template at Porting/release_announcement_template.txt
=head3 update epigraphs.pod
Create a new perldelta.
-B<Note>: currently, the buildtoc below must be run in a I<built> perl source
-directory, as at least one of the pod files it expects to find is
-autogenerated: perluniprops.pod. But you can't build perl if you've added
-the new perldelta file and not updated toc. So, make sure you have a built
-perl (with a pod/perluniprops.pod file) now, I<before> continuing.
-
-First, update the F<pod/.gitignore> file to ignore the next
-release's generated F<pod/perlNNNdelta.pod> file rather than this release's
-one which we are about to set in stone (where NNN is the perl version number
-without the dots. i.e. 5135 for 5.13.5).
-
- $ (edit pod/.gitignore )
- $ git add pod/.gitignore
+=over 4
-Then, move the existing F<pod/perldelta.pod> to F<pod/perlNNNdelta.pod>,
-and edit the moved delta file to change the C<NAME> from C<perldelta> to
-C<perlNNNdelta>. For example, assuming you just released 5.10.1, and are
-about to create the 5.10.2 perldelta:
+=item *
- $ rm pod/perl5101delta.pod # remove the auto-generated file, if any
- $ git mv pod/perldelta.pod pod/perl5101delta.pod
- $ (edit pod/perl5101delta.pod to retitle)
- $ git add pod/perl5101delta.pod
+Confirm that you have a clean checkout with no local changes.
-Then create a new empty perldelta.pod file for the new release; see
-F<Porting/how_to_write_a_perldelta.pod>. 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. Then commit the move and the new file.
+=item *
- $ cp -i Porting/perldelta_template.pod pod/perldelta.pod
- $ (edit pod/perldelta.pod)
- $ git add pod/perldelta.pod
- $ git commit -m 'create perldelta for 5.10.2'
+Run F<Porting/new-perldelta.pl>
-=head3 update perldelta TOC and references
+=item *
-Now you need to update various tables of contents related to perldelta,
-most of which can be generated automatically.
+Run the C<git add> commands it outputs to add new and modified files.
-Edit F<pod.lst>: add the new entry for the perlNNNdelta file for the
-current version (the file that will be symlinked to perldelta).
+=item *
-Manually create a temporary link to the new delta file; normally this is
-done from the Makefile, but the Makefile is updated by buildtoc, and
-buildtoc won't run without the file there:
+Verify that the build still works, by running C<./Configure> and
+C<make test_porting>. (On Win32, run C<nmake> and
+C<nmake test TEST_FILES="porting\*.t ..\lib\diagnostics.t">.)
- $ ln -s perldelta.pod pod/perl5102delta.pod
+=item *
-Run C<perl pod/buildtoc --build-all> to update the F<perldelta> version in
-the following files:
+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.
+Skip to the end of its test output to see the options it offers you.
- MANIFEST
- Makefile.SH
- pod/perl.pod
- vms/descrip_mms.template
- win32/Makefile
- win32/makefile.mk
- win32/pod.mak
+=item *
-Finally, commit:
+When C<make test_porting> passes, commit the new perldelta.
- $ git commit -a -m 'update TOC for perlNNNdelta'
+=back
At this point you may want to compare the commit with a previous bump to
-see if they look similar. See commit dd885b5 for an example of a
+see if they look similar. See commit e3c71926d3 for an example of a
previous version bump.
In particular, F<Porting/perldelta_template.pod> is intentionally exempted
from podchecker tests, to avoid false positives about placeholder text.
However, once it's copied to F<pod/perldelta.pod> the contents can now
-cause test failures. Problems should resolved either by replacing placeholder
-text with correct text, or following the instructions output by
-F<t/porting/podcheck.t> on how to update its exceptions database.
+cause test failures. Problems should resolved by doing one of the
+following:
+
+=over
+
+=item 1
+
+Replace placeholder text with correct text.
+
+=item 2
+
+If the problem is from a broken placeholder link, you can add it to the
+array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines
+containing such links should be marked with C<XXX> so that they get
+cleaned up before the next release.
+
+=item 3
+
+Following the instructions output by F<t/porting/podcheck.t> on how to
+update its exceptions database.
+
+=back
=head3 push commits
=head3 bump RT version number
-Log into http://rt.perl.org/ and check whether the new version is
-in the RT fields C<Perl Version> and C<Fixed In>. If not, send an
-email to C<perlbug-admin at perl.org> requesting this.
+Log into http://rt.perl.org/ and check whether the new version is in the RT
+fields C<Perl Version> and C<Fixed In>. The easiest way to determine this is
+to go to L<https://rt.perl.org/rt3/Search/Build.html> and click on the drop
+downs next to the C<Perl Version> and C<Fixed In> labels.
+
+If the new version is not listed there, send an email to C<perlbug-admin at
+perl.org> requesting this.
=head3 Relax!
https://perl5.git.perl.org / perl5.git / blobdiff