[PATCH v2] CodingGuidelines: a handful of error message guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 28, 2024, 00:36 UTC
Message-ID: <xmqqa5dkqjmr.fsf_-_@gitster.g>
In-Reply-To: <xmqq1pywvmhq.fsf_-_@gitster.g>

Taking input from comments by Eric (thanks) on the previous round, this iteration adds a bit more about Porcelain/Plumbing and BUG().

  diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
  index 71e4742fd5..2b8f99f333 100644
  --- a/Documentation/CodingGuidelines
  +++ b/Documentation/CodingGuidelines
  @@ -703,8 +703,15 @@ Error Messages
    - Enclose the subject of an error inside a pair of single quotes,
      e.g. `die(_("unable to open '%s'"), path)`.
   
  - - Unless there is a compelling reason not to, error messages should
  -   be marked for `_("translation")`.
  + - Unless there is a compelling reason not to, error messages from the
  +   Porcelain command should be marked for `_("translation")`.
  +
  + - Error messages from the plumbing commands are sometimes meant for
  +   machine consumption and should not be marked for `_("translation")`
  +   to keep them 'grep'-able.
  +
  + - BUG("message") are for communicating the specific error to
  +   developers, and not to be translated.
   
   
   Externally Visible Names

--- >8 --- It is more efficient to have something in the coding guidelines document to point at, when we want to review and comment on a new message in the codebase to make sure it "fits" in the set of existing messages.

Let's write down established best practice we are aware of.

Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 3263245b03..2b8f99f333 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -689,16 +689,29 @@ Program Output
 
 Error Messages
 
- - Do not end error messages with a full stop.
+ - Do not end a single-sentence error message with a full stop.
 
  - Do not capitalize the first word, only because it is the first word
-   in the message ("unable to open %s", not "Unable to open %s").  But
+   in the message ("unable to open '%s'", not "Unable to open '%s'").  But
    "SHA-3 not supported" is fine, because the reason the first word is
    capitalized is not because it is at the beginning of the sentence,
    but because the word would be spelled in capital letters even when
    it appeared in the middle of the sentence.
 
- - Say what the error is first ("cannot open %s", not "%s: cannot open")
+ - Say what the error is first ("cannot open '%s'", not "%s: cannot open").
+
+ - Enclose the subject of an error inside a pair of single quotes,
+   e.g. `die(_("unable to open '%s'"), path)`.
+
+ - Unless there is a compelling reason not to, error messages from the
+   Porcelain command should be marked for `_("translation")`.
+
+ - Error messages from the plumbing commands are sometimes meant for
+   machine consumption and should not be marked for `_("translation")`
+   to keep them 'grep'-able.
+
+ - BUG("message") are for communicating the specific error to
+   developers, and not to be translated.
 
 
 Externally Visible Names

-- 
2.47.1-499-g8536fed62d