From e6432e167fb14879eaeb8b0aa742bcee895b2daa Mon Sep 17 00:00:00 2001 From: Florian Dahlitz Date: Thu, 21 May 2020 12:17:23 +0200 Subject: [PATCH 1/4] Fix good commit example to use imperative title - Fix example to use imperative title - Explicitly mention the preference for imperative over descriptive titles - Link to the article from Chris Beams --- pullrequest.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/pullrequest.rst b/pullrequest.rst index 859261948..a1c15c3bb 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -258,21 +258,30 @@ 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 (GH-NNNN) + bpo-42: make the spam module 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. The first line or sentence is meant to be a dense, to-the-point explanation -of what the purpose of the commit is. If this is not enough detail for a -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). +of what the purpose of the commit is. The imperative form is strongly +preferred to a descriptive form such as 'the spam module is now more spammy'. +Use ``git log --oneline`` to see existing title lines. Furthermore, the first +line should not end in a period. + +If this is not enough detail for a 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 ` for further instructions on how the commit message should look like when merging a pull request. +.. note:: + `How to Write a Git Commit Message `_ + is a nice article describing how to write a good commit message. + .. _cla: From a2a902eda11c9a038e49e04b1c91a0c647f06bea Mon Sep 17 00:00:00 2001 From: Florian Dahlitz Date: Fri, 22 May 2020 09:51:50 +0200 Subject: [PATCH 2/4] Apply suggestions from code review @aeros --- pullrequest.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pullrequest.rst b/pullrequest.rst index a1c15c3bb..4dc1c7132 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -264,10 +264,10 @@ Commit messages should follow the following structure:: raises the amount of spam in the module by making it more spammy. The first line or sentence is meant to be a dense, to-the-point explanation -of what the purpose of the commit is. The imperative form is strongly -preferred to a descriptive form such as 'the spam module is now more spammy'. -Use ``git log --oneline`` to see existing title lines. Furthermore, the first -line should not end in a period. +of what the purpose of the commit is. The imperative form (used in the example +above) is strongly preferred to a descriptive form such as 'the spam module is +now more spammy'. Use ``git log --oneline`` to see existing title lines. +Furthermore, the first line should not end in a period. If this is not enough detail for a commit, a new paragraph(s) can be added to explain in proper depth what has happened (detail should be good enough From 7d16a286caed5c6fa9c6b1bdbe4e6126ff36e312 Mon Sep 17 00:00:00 2001 From: Florian Dahlitz Date: Sun, 24 May 2020 10:49:18 +0200 Subject: [PATCH 3/4] Apply suggestion made by @terryjreedy Co-authored-by: Terry Jan Reedy --- pullrequest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pullrequest.rst b/pullrequest.rst index 4dc1c7132..c6632f2d3 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -258,7 +258,7 @@ and for each pull request there may be several commits. In particular: Commit messages should follow the following structure:: - bpo-42: make the spam module more spammy (GH-NNNN) + bpo-42: Make the spam module 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. From 2be1ce902d1f5e9cbca5d518764e40af4f6e48dc Mon Sep 17 00:00:00 2001 From: Florian Dahlitz Date: Mon, 25 May 2020 08:46:30 +0200 Subject: [PATCH 4/4] Apply changes suggested by @aeros Co-authored-by: Kyle Stanley --- pullrequest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pullrequest.rst b/pullrequest.rst index c6632f2d3..1e109e8c3 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -280,7 +280,7 @@ request. .. note:: `How to Write a Git Commit Message `_ - is a nice article describing how to write a good commit message. + is a nice article that describes how to write a good commit message. .. _cla: