Improve instructions on commit messages (python#275)

mariocj89 · ezio-melotti · commit a62b9e38ff2f · 2017-10-12T09:13:29.000-07:00
* 1. Include (GH-NNNN) in the suffix in the first line

* 2. Add link to instructions on how to format the commit

* 3. Information on how to format a backport commit

* 4. Move GH-NNN to the body on long titles

* Comments from review

* Comments from Mariatta

* Minor consistency tweak.
diff --git a/gitbootcamp.rst b/gitbootcamp.rst
@@ -323,6 +323,8 @@ local copy of a pull request as follows::
    $ git pr <pr_number>
 
 
+.. _accepting-and-merging-a-pr:
+
 Accepting and Merging A Pull Request
 ------------------------------------
 
@@ -331,7 +333,8 @@ Pull requests can be accepted and merged by a Python Core Developer.
 1. At the bottom of the pull request page, click the ``Squash and merge``
    button.
 
-2. Replace the reference to GitHub PR #XXX into GH-XXX.
+2. Replace the reference to GitHub PR #NNNN into GH-NNNN. If the title
+   is too long, the pull request number can be added to the body.
 
 3. Adjust and clean up the commit message.
 
@@ -381,6 +384,16 @@ Alternatively, the commit hash can also be obtained by the following git command
 The above commands will print out the hash of the commit containing ``"bpo-12345"``
 as part of the commit message.
 
+When formatting the message for a backport commit: leave it as the the original
+one, pointing to the original pull request number as well (``GH-NNNN``).
+
+Example of good backport commit message::
+
+    bpo-12345: Improve the spam module (GH-777)
+
+    * Add method A to the spam module
+    * Update the documentation of the spam module
+
 
 Editing a Pull Request Prior to Merging
 ---------------------------------------
diff --git a/pullrequest.rst b/pullrequest.rst
@@ -210,7 +210,7 @@ and for each pull request there may be several commits.  In particular:
 
 Commit messages should follow the following structure::
 
-   bpo-42: the spam module is now more spammy.
+   bpo-42: the spam module is now more spammy. (GH-NNNN)
 
    The spam module sporadically came up short on spam. This change
    raises the amount of spam in the module by making it more spammy.
@@ -221,6 +221,9 @@ commit, a new paragraph(s) can be added to explain in proper depth what has
 happened (detail should be good enough that a core developer reading the
 commit message understands the justification for the change).
 
+Check :ref:`the git bootcamp <accepting-and-merging-a-pr>` for further
+instructions on how the commit should look like when merging a pull request.
+
 
 .. _cla:
 
