add release branch steps to rmg

[perl5.git] / Porting / release_managers_guide.pod

diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 8729b82..8ab01d6 100644 (file)
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -184,20 +184,27 @@ but all I<must> be done in the run up to a release.
 
 =head3 dual-life CPAN module synchronisation
 
-Ensure that dual-life CPAN modules are synchronised with CPAN.  Basically,
-run the following:
+To see which core distro versions differ from the current CPAN versions:
 
-    $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+    $ ./perl -Ilib Porting/core-cpan-diff -x -a
 
-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
-C<-d> and C<-v> options for more detail.  You'll probably want to use the
-C<-c cachedir> option to avoid repeated CPAN downloads and may want to
-use C<-m file:///mirror/path> if you made a local CPAN mirror.
+Passing C<-u cpan> (and maybe C<-u undef>) will probably be helpful, since
+those are the only types of distributions that you can actually affect as a
+perl release manager (as opposed to a CPAN module maintainer).
 
-To see which core distro versions differ from the current CPAN versions:
+You can also run an actual diff of the contents of the modules, comparing core
+to CPAN, to ensure that there were no erroneous/extraneous changes that need to
+be dealt with. You do this by not passing the C<-x> option:
 
-    $ ./perl -Ilib Porting/core-cpan-diff -x -a
+    $ ./perl -Ilib Porting/core-cpan-diff -a -o /tmp/corediffs
+
+then fix the core, or cajole CPAN authors as appropriate. See also the C<-d>
+and C<-v> options for more detail (and the C<-u> option as mentioned above).
+You'll probably want to use the C<-c cachedir> option to avoid repeated CPAN
+downloads and may want to use C<-m file:///mirror/path> if you made a local
+CPAN mirror. Note that a minicpan mirror won't actually work, but can provide a
+good first pass to quickly get a list of modules which definitely haven't
+changed, to avoid having to download absolutely everything.
 
 If you are making a MAINT release, run C<core-cpan-diff> on both blead and
 maint, then diff the two outputs. Compare this with what you expect, and if
@@ -220,7 +227,7 @@ directory to the original name.
 
 =item *
 
-Restore any F<.gitignore> file. This can be done by issueing 
+Restore any F<.gitignore> file. This can be done by issuing
 C<git checkout .gitignore> in the F<cpan/Distro> directory.
 
 =item *
@@ -375,6 +382,8 @@ After editing, regenerate uconfig.h (this must be run on a system with a
 
     $ perl regen/uconfig_h.pl
 
+This might not cause any new changes.
+
 Test your changes:
 
     $ git clean -xdf   # careful if you don't have local files to keep!
@@ -448,6 +457,16 @@ L<"Building a release - advance actions"> to ensure they are all done and
 up-to-date.
 
 
+=head3 create a release branch
+
+For BLEAD-POINT releases, making a release from a release branch avoids the
+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
+
+
 =head3 bump version number
 
 For a BLEAD-POINT release, if you did not bump the perl version number as
@@ -681,9 +700,9 @@ 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-deadbeef))
+ This is perl 5, version X, subversion Y (v5.X.Y (v5.X.Z-NNN-gdeadbeef))
 
-where 5.X.Z is the latest tag, Z the number of commits since this tag,
+where 5.X.Z is the latest tag, NNN the number of commits since this tag,
 and C<< deadbeef >> commit of that tag.
 
 Then delete the temporary installation.
@@ -968,6 +987,18 @@ Use the template at Porting/release_announcement_template.txt
 
 Send a carbon copy to C<noc@metacpan.org>
 
+=head3 merge release branch back to blead
+
+If you made a release branch for this release, merge it back into master now,
+and delete it.
+
+  git checkout blead
+  git pull
+  git merge release-5.xx.yy
+  git push
+  git push origin :release-5.xx.yy
+  git branch -d release-5.xx.yy
+
 =head3 update epigraphs.pod
 
 Add your quote to F<Porting/epigraphs.pod> and commit it.