git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: git@vger.kernel.org
Subject: [PATCH v2 1/3] SubmittingPatches: write problem statement in the log in the present tense
Date: Wed, 26 Jan 2022 15:42:03 -0800	[thread overview]
Message-ID: <20220126234205.2923388-2-gitster@pobox.com> (raw)
In-Reply-To: <20220126234205.2923388-1-gitster@pobox.com>

We give a guidance for proposed log message to write problem
statement first, followed by the reasoning behind, and recipe for,
the solution.  Clarify that we describe the situation _before_ the
proposed patch is applied in the present tense (not in the past
tense e.g. "we used to do X, but thanks to this commit we now do Y")
for consistency.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 92b80d94d4..7225a0fb52 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -142,6 +142,13 @@ The body should provide a meaningful commit message, which:
 
 . alternate solutions considered but discarded, if any.
 
+[[present-tense]]
+The problem statement that describes the status quo is written in the
+present tense.  Write "The code does X when it is given input Y",
+instead of "The code used to do Y when given input X".  You do not
+have to say "Currently"---the status quo in the problem statement is
+about the code _without_ your change, by project convention.
+
 [[imperative-mood]]
 Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
-- 
2.35.0-155-g0eb5153edc


  reply	other threads:[~2022-01-26 23:42 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-23 20:37 [RFC] Contributor doc: more on the proposed log message Junio C Hamano
2022-01-23 21:32 ` brian m. carlson
2022-01-26 11:07   ` Kaartic Sivaraam
2022-01-26 23:42 ` [PATCH v2 0/3] contributor doc update around log messages Junio C Hamano
2022-01-26 23:42   ` Junio C Hamano [this message]
2022-01-26 23:42   ` [PATCH v2 2/3] CodingGuidelines: hint why we value clearly written " Junio C Hamano
2022-01-27  7:31     ` Eric Sunshine
2022-01-27 18:35       ` Junio C Hamano
2022-01-26 23:42   ` [PATCH v2 3/3] SubmittingPatches: explain why we care about " Junio C Hamano
2022-01-27 19:02   ` [PATCH v3 0/3] contributor doc update around " Junio C Hamano
2022-03-04  0:12     ` Emily Shaffer
2022-01-27 19:02   ` [PATCH v3 1/3] SubmittingPatches: write problem statement in the log in the present tense Junio C Hamano
2022-03-03 23:59     ` Emily Shaffer
2022-03-04  0:23       ` Junio C Hamano
2022-03-04 23:41         ` Emily Shaffer
2022-01-27 19:02   ` [PATCH v3 2/3] CodingGuidelines: hint why we value clearly written log messages Junio C Hamano
2022-03-04  0:07     ` Emily Shaffer
2022-03-04  0:27       ` Junio C Hamano
2022-04-14  6:51         ` Junio C Hamano
2022-04-14 14:04           ` Ævar Arnfjörð Bjarmason
2022-04-19 22:53             ` Emily Shaffer
2022-04-20  8:23               ` Junio C Hamano
2022-01-27 19:02   ` [PATCH v3 3/3] SubmittingPatches: explain why we care about " Junio C Hamano
2022-03-04  0:10     ` Emily Shaffer
2022-03-04  0:29       ` Junio C Hamano
2022-03-04  9:52         ` log messages > comments (was: [PATCH v3 3/3] SubmittingPatches: explain why we care about log messages) Ævar Arnfjörð Bjarmason
2022-03-04 19:41           ` log messages > comments Junio C Hamano
2022-03-04 21:30             ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220126234205.2923388-2-gitster@pobox.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).