Update perlgit and perlhack to reference GitHub pull request workflow

(cherry picked from commit 617d9ec40b6f4f34796deb5007320a135e402779)

2 files changed, 48 insertions, 72 deletions

diff --git a/pod/perlgit.pod b/pod/perlgit.pod
index c34e70917d..67aa0b4038 100644
--- a/pod/perlgit.pod
+++ b/pod/perlgit.pod
@@ -255,26 +255,32 @@ itself you can fix it up by editing the files once more and then issue:
 
   % git commit -a --amend
 
-Now you should create a patch file for all your local changes:
+Now, create a fork on GitHub to push your branch to, and add it as a
+remote if you haven't already, as described in the GitHub documentation
+at L<https://help.github.com/en/articles/working-with-forks>:
 
-  % git format-patch -M blead..
-  0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
+  % git remote add fork git@github.com:MyUser/perl5.git
 
-Or for a lot of changes, e.g. from a topic branch:
+And push the branch to your fork:
 
-  % git format-patch --stdout -M blead.. > topic-branch-changes.patch
+  % git push -u fork orange
 
-You should now send an email to
-L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your
-changes, and include this patch file as an attachment. In addition to
-being tracked by RT, mail to perlbug will automatically be forwarded to
-perl5-porters (with manual moderation, so please be patient). You
-should only send patches to
+You should now submit a Pull Request (PR) on GitHub from the new branch
+to blead. For more information, see the GitHub documentation at
+L<https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>.
+
+You can also send patch files to
 L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the
 patch is not ready to be applied, but intended for discussion.
 
-Please do not use git-send-email(1) to send your patch. See L<Sending
-patch emails|/Sending patch emails> for more information.
+To create a patch file for all your local changes:
+
+  % git format-patch -M blead..
+  0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
+
+Or for a lot of changes, e.g. from a topic branch:
+
+  % git format-patch --stdout -M blead.. > topic-branch-changes.patch
 
 If you want to delete your temporary branch, you may do so with:
 
@@ -285,30 +291,6 @@ If you want to delete your temporary branch, you may do so with:
  % git branch -D orange
  Deleted branch orange.
 
-=head2 Sending patch emails
-
-After you've generated your patch you should send it
-to L<perlbug@perl.org|mailto:perlbug@perl.org> (as discussed L<in the
-previous section|/"Patch workflow">) with a normal mail client as an
-attachment, along with a description of the patch.
-
-You B<must not> use git-send-email(1) to send patches generated with
-git-format-patch(1). The RT ticketing system living behind
-L<perlbug@perl.org|mailto:perlbug@perl.org> does not respect the inline
-contents of E-Mails, sending an inline patch to RT guarantees that your
-patch will be destroyed.
-
-Someone may download your patch from RT, which will result in the
-subject (the first line of the commit message) being omitted.  See
-L<RT #74192|https://rt.perl.org/Ticket/Display.html?id=74192> and
-L<commit a4583001|https://github.com/Perl/perl5/commit/a4583001>
-for an example. Alternatively someone may
-apply your patch from RT after it arrived in their mailbox, by which
-time RT will have modified the inline content of the message.  See
-L<RT #74532|https://rt.perl.org/Ticket/Display.html?id=74532> and
-L<commit f9bcfeac|https://github.com/Perl/perl5/commit/f9bcfeac>
-for a bad example of this failure mode.
-
 =head2 A note on derived files
 
 Be aware that many files in the distribution are derivative--avoid
diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index d05e12e711..b9f2b5ffd2 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -11,7 +11,7 @@ perlhack - How to hack on Perl
 =head1 DESCRIPTION
 
 This document explains how Perl development works.  It includes details
-about the Perl 5 Porters email list, the Perl repository, the Perlbug
+about the Perl 5 Porters email list, the Perl repository, the Perl
 bug tracker, patch guidelines, and commentary on Perl development
 philosophy.
 
@@ -36,6 +36,13 @@ latest version directly from the perl source:
 
   % perldoc pod/perlhack.pod
 
+=item * Create a branch for your change
+
+Create a branch based on blead to commit your change to, which will
+later be used to send it to the Perl issue tracker.
+
+  % git checkout -b mychange
+
 =item * Make your change
 
 Hack, hack, hack.  Keep in mind that Perl runs on many different
@@ -61,29 +68,23 @@ Committing your work will save the change I<on your local system>:
 Make sure the commit message describes your change in a single
 sentence.  For example, "Fixed spelling errors in perlhack.pod".
 
-=item * Send your change to perlbug
+=item * Send your change to the Perl issue tracker
 
-The next step is to submit your patch to the Perl core ticket system
-via email.
+The next step is to submit your patch to the Perl core ticket system.
 
-If your changes are in a single git commit, run the following commands
-to generate the patch file and attach it to your bug report:
+Create a GitHub fork of the perl5 repository and add it as a remote,
+if you haven't already, as described in the GitHub documentation at
+L<https://help.github.com/en/articles/working-with-forks>.
 
-  % git format-patch -1
-  % ./perl -Ilib utils/perlbug -p 0001-*.patch
+  % git remote add fork git@github.com:MyUser/perl5.git
 
-The perlbug program will ask you a few questions about your email
-address and the patch you're submitting.  Once you've answered them it
-will submit your patch via email.
+Then, push your new branch to your fork.
 
-If your changes are in multiple commits, generate a patch file for each
-one and provide them to perlbug's C<-p> option separated by commas:
+  % git push -u fork mychange
 
-  % git format-patch -3
-  % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\
-  > 0003-fix3.patch
-
-When prompted, pick a subject that summarizes your changes.
+Finally, create a Pull Request on GitHub from your branch to blead as
+described in the GitHub documentation at
+L<https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>.
 
 =item * Thank you
 
@@ -107,6 +108,7 @@ latest perl in a pristine state.  Check you don't have any local changes
 or added files in your perl check-out which you wish to keep, then run
 these commands:
 
+  % git checkout blead
   % git pull
   % git reset --hard origin/blead
   % git clean -dxf
@@ -218,27 +220,15 @@ Perl source.
 
 =head2 Submitting patches
 
-If you have a small patch to submit, please submit it via perlbug.  You
-can also send email directly to perlbug@perl.org.  Please note that
-messages sent to perlbug may be held in a moderation queue, so you
-won't receive a response immediately.
+If you have a small patch to submit, please submit it via the GitHub
+Pull Request workflow.  You may also send patches to the p5p list.
 
-You'll know your submission has been processed when you receive an
-email from our ticket tracking system.  This email will give you a
-ticket number.  Once your patch has made it to the ticket tracking
-system, it will also be sent to the perl5-porters@perl.org list.
-
-If your patch is related to an already-opened ticket you can also
-attach your patch to that ticket, without having to use perlbug.
-
-Patches are reviewed and discussed on the p5p list.  Simple,
+Patches are reviewed and discussed on GitHub or the p5p list.  Simple,
 uncontroversial patches will usually be applied without any discussion.
 When the patch is applied, the ticket will be updated and you will
-receive email.  In addition, an email will be sent to the p5p list.
-
-In other cases, the patch will need more work or discussion.  That will
-happen on the p5p list.
+receive email.
 
+In other cases, the patch will need more work or discussion.
 You are encouraged to participate in the discussion and advocate for
 your patch.  Sometimes your patch may get lost in the shuffle.  It's
 appropriate to send a reminder email to p5p if no action has been taken
@@ -258,6 +248,10 @@ can do to help the Perl 5 Porters accept your patch.
 
 =head3 Patch style
 
+Using the GitHub Pull Request workflow, your patch will automatically
+be available in a suitable format.  If you wish to submit a patch to
+the p5p list for review, make sure to create it appropriately.
+
 If you used git to check out the Perl source, then using C<git
 format-patch> will produce a patch in a style suitable for Perl.  The
 C<format-patch> command produces one patch file for each commit you