From: Philip Oakley <philipoakley@iee.org>
Date: Tue, 15 Jul 2014 19:28:06 GMT
Subject: Re: [PATCH] doc: State coding guideline for error message punctuation
Message-ID: <93D8A848078245C2BA36B26D878B5970@PhilipOakley>
In-Reply-To: <xmqqwqbl6jey.fsf@gitster.dls.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Thursday, July 10, 2014 9:36 PM
> Jeff King <peff@peff.net> writes:
>
>> On Mon, Jun 16, 2014 at 01:55:57PM +0100, Philip Oakley wrote:
>>
>>> +Error Messages
>>> +
>>> + - We typically do not end error messages with a full stop. While
>>> +   we've been rather inconsistent in the past, these days we mostly
>>> +   settle on no punctuation.
>>
>> Unlike Junio, I do not mind spelling out guidance for error messages.
>> However, I do not think the second sentence is adding anything here
>> (everything in CodingGuidelines is subject to "we did not always do 
>> it
>> this way, but this is the preferred way now"). So I'd drop it.
>>
>> And then add in more guidance. Besides "no full stop", probably:
>>
>>   1. do not capitalize ("unable to open %s", not "Unable to open %s"
>>
>>   2. maybe something on sentence structure / ordering? We tend to 
>> prefer
>>      "cannot open 'foo': No such file or directory" to "foo: cannot
>>      open: No such file or directory".
>>
>> Perhaps there are others (we do not have to be exhaustive, but it 
>> makes
>> sense to think for a moment while we are here).
>
> I do not want to forever be waiting for a reroll, so let's queue
> this and advance it to 'next' soonish, and refine the guidelines by
> further building on top of it as needed.
>

Sorry, I've been away on vacation for the last few weeks. I hadn't been 
sure what to include in a re-roll without it gaining too much mission 
creep.

Thanks for keeping an eye on it.


> Thanks.
>
> -- >8 --
> From: Philip Oakley <philipoakley@iee.org>
> Date: Mon, 16 Jun 2014 13:55:57 +0100
> Subject: [PATCH] doc: give some guidelines for error messages
>
> Clarify error message puntuation to reduce review workload.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> Helped-by: Jeff King <peff@peff.net>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/CodingGuidelines | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
> diff --git a/Documentation/CodingGuidelines 
> b/Documentation/CodingGuidelines
> index f424dbd..f4137c6 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -264,6 +264,15 @@ For Python scripts:
>    documentation for version 2.6 does not mention this prefix, it has
>    been supported since version 2.6.0.
>
> +Error Messages
> +
> + - Do not end error messages with a full stop.
> +
> + - Do not capitalize ("unable to open %s", not "Unable to open %s")
> +
> + - Say what the error is first ("cannot open %s", not "%s: cannot 
> open")
> +
> +
> Writing Documentation:
>
>  Most (if not all) of the documentation pages are written in the
> -- 
> 2.0.1-751-ge540734
>