{"thread":{"id":"55495","subject":"[PATCH] doc: clarify \"do not capitalize the first word\" rule","startedAt":"2021-04-14T23:51:20Z","lastAt":"2021-04-15T09:16:08Z","messageCount":2,"participants":["Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"421995","messageId":"xmqq7dl4whl6.fsf@gitster.g","threadId":"55495","inReplyTo":null,"subject":"[PATCH] doc: clarify \"do not capitalize the first word\" rule","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-14T23:51:17Z","receivedAt":"2021-04-14T23:51:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The same \"do not capitalize the first word\" rule is applied to both\nour patch titles and error messages, but the existing description\nwas fuzzy in two aspects.\n\n * For error messages, it was not said that this was only about the\n   first word that begins the sentence.\n\n * For both, it was not clear when a capital letter there was not an\n   error.  We avoid capitalizing the first word when the only reason\n   you would capitalize it is because it happens to be the first\n   word in the sentence.  If a proper noun that is usually spelled\n   in caps happens to come at the beginning of the sentence, that is\n   not a reason to downcase it.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n * I saw in the GGG inbox a well-intended patch that took the \"do\n   not capitalize\" rule too far, but with documentation unclear, it\n   was understandable, so here is to remedy the situation.\n\n Documentation/CodingGuidelines  |  7 ++++++-\n Documentation/SubmittingPatches | 11 +++++++----\n 2 files changed, 13 insertions(+), 5 deletions(-)\n\ndiff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines\nindex 45465bc0c9..86d2afd6d2 100644\n--- c/Documentation/CodingGuidelines\n+++ w/Documentation/CodingGuidelines\n@@ -498,7 +498,12 @@ Error Messages\n \n  - Do not end error messages with a full stop.\n \n- - Do not capitalize (\"unable to open %s\", not \"Unable to open %s\")\n+ - Do not capitalize the first word, only because the word is the\n+   first word in the message (\"unable to open %s\", not \"Unable to open\n+   %s\", but \"SHA-3 not supported\" is fine, as the reason the first\n+   word is capitalized is not because it is at the beginning of the\n+   sentence, but because the word would be spelled with caps even when\n+   it appeared in the middle of the sentence).\n \n  - Say what the error is first (\"cannot open %s\", not \"%s: cannot open\")\n \ndiff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches\nindex 0452db2e67..aee56cf127 100644\n--- c/Documentation/SubmittingPatches\n+++ w/Documentation/SubmittingPatches\n@@ -117,10 +117,13 @@ If in doubt which identifier to use, run `git log --no-merges` on the\n files you are modifying to see the current conventions.\n \n [[summary-section]]\n-It's customary to start the remainder of the first line after \"area: \"\n-with a lower-case letter. E.g. \"doc: clarify...\", not \"doc:\n-Clarify...\", or \"githooks.txt: improve...\", not \"githooks.txt:\n-Improve...\".\n+The title sentence after the \"area:\" prefix omits the full stop at the\n+end, and its first word is not capitalized unless there is a reason to\n+capitalize it other than that it is the first word in the sentence.\n+E.g. \"doc: clarify...\", not \"doc: Clarify...\", or \"githooks.txt:\n+improve...\", not \"githooks.txt: Improve...\".  But \"refs: HEAD is also\n+treated as a ref\" is correct, as we spell `HEAD` in all caps even when\n+it appears in the middle of a sentence.\n \n [[meaningful-message]]\n The body should provide a meaningful commit message, which:\n"},{"id":"422015","messageId":"YHgEVZ/vN5hEAgoQ@coredump.intra.peff.net","threadId":"55495","inReplyTo":"xmqq7dl4whl6.fsf@gitster.g","subject":"Re: [PATCH] doc: clarify \"do not capitalize the first word\" rule","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-04-15T09:16:05Z","receivedAt":"2021-04-15T09:16:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Apr 14, 2021 at 04:51:17PM -0700, Junio C Hamano wrote:\n\n> The same \"do not capitalize the first word\" rule is applied to both\n> our patch titles and error messages, but the existing description\n> was fuzzy in two aspects.\n> \n>  * For error messages, it was not said that this was only about the\n>    first word that begins the sentence.\n> \n>  * For both, it was not clear when a capital letter there was not an\n>    error.  We avoid capitalizing the first word when the only reason\n>    you would capitalize it is because it happens to be the first\n>    word in the sentence.  If a proper noun that is usually spelled\n>    in caps happens to come at the beginning of the sentence, that is\n>    not a reason to downcase it.\n> \n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n> \n>  * I saw in the GGG inbox a well-intended patch that took the \"do\n>    not capitalize\" rule too far, but with documentation unclear, it\n>    was understandable, so here is to remedy the situation.\n\nAfter reading the patch, I wouldn't have thought it needed to be spelled\nout, but if you saw a case in the wild, it doesn't hurt to be as clear\nas possible.\n\nThe patch text itself looks good to me.\n\n-Peff\n"}]}