doc: clarify "do not capitalize the first word" rule
The same "do not capitalize the first word" rule is applied to both our patch titles and error messages, but the existing description was fuzzy in two aspects. * For error messages, it was not said that this was only about the first word that begins the sentence. * For both, it was not clear when a capital letter there was not an error. We avoid capitalizing the first word when the only reason you would capitalize it is because it happens to be the first word in the sentence. If a proper noun, which is usually spelled in capital letters, happens to come at the beginning of the sentence, it should be kept in capital letters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Apr 14, 2021 at 16:51 UTC
151b6c2dd7d040bd053911e4fd4b3e5cc6f17c83
2 files changed
+13
-5
Documentation/CodingGuidelines
+6
-1
@@ -498,7 +498,12 @@ Error Messages
498
499
- Do not end error messages with a full stop.
500
501
- - Do not capitalize ("unable to open %s", not "Unable to open %s")
501
+ - Do not capitalize the first word, only because it is the first word
502
+ in the message ("unable to open %s", not "Unable to open %s"). But
503
+ "SHA-3 not supported" is fine, because the reason the first word is
504
+ capitalized is not because it is at the beginning of the sentence,
505
+ but because the word would be spelled in capital letters even when
506
+ it appeared in the middle of the sentence.
507
508
- Say what the error is first ("cannot open %s", not "%s: cannot open")
509
Documentation/SubmittingPatches
+7
-4
@@ -117,10 +117,13 @@ If in doubt which identifier to use, run `git log --no-merges` on the
117
files you are modifying to see the current conventions.
118
119
[[summary-section]]
120
-It's customary to start the remainder of the first line after "area: "
121
-with a lower-case letter. E.g. "doc: clarify...", not "doc:
122
-Clarify...", or "githooks.txt: improve...", not "githooks.txt:
123
-Improve...".
120
+The title sentence after the "area:" prefix omits the full stop at the
121
+end, and its first word is not capitalized unless there is a reason to
122
+capitalize it other than because it is the first word in the sentence.
123
+E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
124
+improve...", not "githooks.txt: Improve...". But "refs: HEAD is also
125
+treated as a ref" is correct, as we spell `HEAD` in all caps even when
126
+it appears in the middle of a sentence.
127
128
[[meaningful-message]]
129
The body should provide a meaningful commit message, which: