Re: [PATCH 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..."
Ævar Arnfjörð Bjarmason writes: > ...it makes this subsequent example more succinct and clear, because > e.g. "githooks.txt" is shorter than "git-cherry-pick.txt", and > "clarify" is obviously a normal looking word... Ah, that makes sense. Thanks.
Re: [PATCH 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..."
On Sat, Mar 18, 2017 at 8:04 PM, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason writes: > >> prefix the first line with "area: " where the area is a filename or >> identifier for the general area of the code being modified, e.g. >> >> - . archive: ustar header checksum is computed unsigned >> - . git-cherry-pick.txt: clarify the use of revision range notation >> + . doc: clarify distinction between sign-off and pgp-signing >> + . githooks.txt: improve the intro section > > Sorry, but I fail to spot why this is an improvement (it is not > making things worse, either). Because... >> If in doubt which identifier to use, run "git log --no-merges" on the >> files you are modifying to see the current conventions. >> >> +It's customary to start the remainder of the first line after "area: " >> +with a lower-case letter. E.g. "doc: clarify...", not "doc: >> +Clarify...", or "githooks.txt: improve...", not "githooks.txt: >> +Improve...". ...it makes this subsequent example more succinct and clear, because e.g. "githooks.txt" is shorter than "git-cherry-pick.txt", and "clarify" is obviously a normal looking word which you'd expect to be capitalized after a full stop, but it might take a couple of readings to understand that "unstar" without a hyphen isn't some jargon.
Re: [PATCH 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..."
Ævar Arnfjörð Bjarmason writes: > prefix the first line with "area: " where the area is a filename or > identifier for the general area of the code being modified, e.g. > > - . archive: ustar header checksum is computed unsigned > - . git-cherry-pick.txt: clarify the use of revision range notation > + . doc: clarify distinction between sign-off and pgp-signing > + . githooks.txt: improve the intro section Sorry, but I fail to spot why this is an improvement (it is not making things worse, either). > If in doubt which identifier to use, run "git log --no-merges" on the > files you are modifying to see the current conventions. > > +It's customary to start the remainder of the first line after "area: " > +with a lower-case letter. E.g. "doc: clarify...", not "doc: > +Clarify...", or "githooks.txt: improve...", not "githooks.txt: > +Improve...".
[PATCH 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..."
Amend the section which describes how the first line of the subject should look like to say that the ":" in "area: " shouldn't be treated like a full stop for the purposes of letter casing. Change the two subject examples to make this new paragraph clearer, i.e. "unstar" is not a common word, and "git-cherry-pick.txt" is a much longer string than "githooks.txt". Pick two recent commits from git.git that fit better for the description. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/SubmittingPatches | 9 +++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3faf7eb884..9ef624ce38 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -98,12 +98,17 @@ should skip the full stop. It is also conventional in most cases to prefix the first line with "area: " where the area is a filename or identifier for the general area of the code being modified, e.g. - . archive: ustar header checksum is computed unsigned - . git-cherry-pick.txt: clarify the use of revision range notation + . doc: clarify distinction between sign-off and pgp-signing + . githooks.txt: improve the intro section If in doubt which identifier to use, run "git log --no-merges" on the files you are modifying to see the current conventions. +It's customary to start the remainder of the first line after "area: " +with a lower-case letter. E.g. "doc: clarify...", not "doc: +Clarify...", or "githooks.txt: improve...", not "githooks.txt: +Improve...". + The body should provide a meaningful commit message, which: . explains the problem the change tries to solve, iow, what is wrong -- 2.11.0
