From patchwork Wed Jan 26 23:42:03 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 12725926 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0F33EC433F5 for ; Wed, 26 Jan 2022 23:42:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230263AbiAZXmM (ORCPT ); Wed, 26 Jan 2022 18:42:12 -0500 Received: from pb-smtp2.pobox.com ([64.147.108.71]:58346 "EHLO pb-smtp2.pobox.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229470AbiAZXmM (ORCPT ); Wed, 26 Jan 2022 18:42:12 -0500 Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 7DD96103ECF; Wed, 26 Jan 2022 18:42:11 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=gfcivo8vUxbiIUcuTKllSms8V jeOkW7NATG62jYZCrE=; b=yR6nco+4p5Iq/1APrLgTG4NagKRn+hWinT3ZcGaAU zOBH2ml2z+JB1gUmKgfQf2iw1IRnXpAG87MbelMnQ1C5mzxfYf2Pc96bWa8TPvdJ tblFS0GZ39F9lyhiMjkBRH06i9q/98T/tlKHxd1CmfJKBUTBytQQzO53RGARhDJq /Q= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 7698A103ECD; Wed, 26 Jan 2022 18:42:11 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [104.133.2.91]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id E0CA7103ECC; Wed, 26 Jan 2022 18:42:10 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano 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 Message-Id: <20220126234205.2923388-2-gitster@pobox.com> X-Mailer: git-send-email 2.35.0-168-gb86c5231e1 In-Reply-To: <20220126234205.2923388-1-gitster@pobox.com> References: <20220126234205.2923388-1-gitster@pobox.com> MIME-Version: 1.0 X-Pobox-Relay-ID: 94C61346-7F01-11EC-96BE-CB998F0A682E-77302942!pb-smtp2.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 From patchwork Wed Jan 26 23:42:04 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 12725927 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 73577C433F5 for ; Wed, 26 Jan 2022 23:42:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230408AbiAZXmR (ORCPT ); Wed, 26 Jan 2022 18:42:17 -0500 Received: from pb-smtp21.pobox.com ([173.228.157.53]:62835 "EHLO pb-smtp21.pobox.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231946AbiAZXmQ (ORCPT ); Wed, 26 Jan 2022 18:42:16 -0500 Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 0FA68179584; Wed, 26 Jan 2022 18:42:15 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=ySNTZM05VGhw/fv3BQtzh3m2g JuIQ+l2vmcYIut+Eu4=; b=SvHDT9h1wJrfEyTXmA3SVrCY2TUfiaQUAF8PePAJz Ku7DLnbjs1aE/1SKwc7o8PVjW0HQP7G/NEt51zyJegF9I38VEnp7aUAjY6zTTjYU ez7RkJG9/6VQxGgr5RDfq9BkhJ7wHELADMCasA/ASTC0HWegdxSAMUwnePuf8ggG To= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 093C9179583; Wed, 26 Jan 2022 18:42:15 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [104.133.2.91]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id 753BF179582; Wed, 26 Jan 2022 18:42:12 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Subject: [PATCH v2 2/3] CodingGuidelines: hint why we value clearly written log messages Date: Wed, 26 Jan 2022 15:42:04 -0800 Message-Id: <20220126234205.2923388-3-gitster@pobox.com> X-Mailer: git-send-email 2.35.0-168-gb86c5231e1 In-Reply-To: <20220126234205.2923388-1-gitster@pobox.com> References: <20220126234205.2923388-1-gitster@pobox.com> MIME-Version: 1.0 X-Pobox-Relay-ID: 95B3D694-7F01-11EC-A150-CBA7845BAAA9-77302942!pb-smtp21.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 0e27b5395d..5f40595f6e 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -26,6 +26,13 @@ code. For Git in general, a few rough rules are: go and fix it up." Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + - Log messages to explain your changes are as much important as the + changes themselves. Clearly written code and in-code comments + explain how the code works and what is assumed from the surrounding + context. The log messages explain what the changes wanted to + achieve and why the changes were necessary (more on this in the + accompanying SubmittingPatches document). + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code From patchwork Wed Jan 26 23:42:05 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 12725928 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4DDBDC433EF for ; Wed, 26 Jan 2022 23:42:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229491AbiAZXmS (ORCPT ); Wed, 26 Jan 2022 18:42:18 -0500 Received: from pb-smtp1.pobox.com ([64.147.108.70]:62295 "EHLO pb-smtp1.pobox.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229709AbiAZXmQ (ORCPT ); Wed, 26 Jan 2022 18:42:16 -0500 Received: from pb-smtp1.pobox.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id E9E7F11EE51; Wed, 26 Jan 2022 18:42:15 -0500 (EST) (envelope-from gitster@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=sasl; bh=io24vVoyOqLZuFV9ulHMwZtoW GMP+7V02GnXweli/MM=; b=Xr4PsRq4UCH9N+18jUI3kPf6p+lhcwbCr6jeRBM3m 7u5k24bpCB6AKwGgv9ec0e/ElJ3f293f8QJYnj0yZ0I/3rgjySGdrvGyhxe60yTJ W/5yTsI9p99sMiXNdc+wfkkO1XcHb0ZjqWin3JkYhsjBJyi+OWbFNjafyYbesUA0 N0= Received: from pb-smtp1.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id E294011EE50; Wed, 26 Jan 2022 18:42:15 -0500 (EST) (envelope-from gitster@pobox.com) Received: from pobox.com (unknown [104.133.2.91]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp1.pobox.com (Postfix) with ESMTPSA id 4939B11EE4F; Wed, 26 Jan 2022 18:42:15 -0500 (EST) (envelope-from gitster@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Subject: [PATCH v2 3/3] SubmittingPatches: explain why we care about log messages Date: Wed, 26 Jan 2022 15:42:05 -0800 Message-Id: <20220126234205.2923388-4-gitster@pobox.com> X-Mailer: git-send-email 2.35.0-168-gb86c5231e1 In-Reply-To: <20220126234205.2923388-1-gitster@pobox.com> References: <20220126234205.2923388-1-gitster@pobox.com> MIME-Version: 1.0 X-Pobox-Relay-ID: 97631D42-7F01-11EC-B442-5E84C8D8090B-77302942!pb-smtp1.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Extend the "describe your changes well" section to cover whom we are trying to help by doing so in the first place. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7225a0fb52..9c5977fac3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -110,6 +110,34 @@ run `git diff --check` on your changes before you commit. [[describe-changes]] === Describe your changes well. +The log message that explains your changes is as much important as the +changes themselves. Your code may be clearly written with in-code +comment to sufficiently explain how it works with the surrounding +code, but those who need to fix or enhance your code in the future +will need to know _why_ your code does what it does, for a few reasons: + +. Your code may be doing something differently from what you wanted it + to do. Writing down what you actually wanted to achieve will help + them fix your code and make it do what it should have been doing + (also, you often discover your own bug while writing your log + message yourself). + +. Your code may be doing things that were only necessary for your + immediate needs (e.g. "do X to directories" without implementing or + even designing what is to be done on files). Writing down why you + excluded what the code does not do will help guide future developers + (e.g. writing down "we do X to directories, because directories have + characteristic Y" would help them infer "oh, files also have the + same characteristic Y, so perhaps doing X to them would also make + sense?". Or "we don't do the same X to files, because ..." will + help them decide if the reasoning is sound (in which case they do + not waste time extending your code to cover files), or reason + differently (in which case they explain why they extend your code to + cover files, too). + +The goal of your log message is to convey the _why_ behind your +change to help them. + The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), and should skip the full stop. It is also conventional in most cases to