[PATCH] SubmittingPatches: Cite the 50 char subject limit

[PATCH] SubmittingPatches: Cite the 50 char subject limit

[Ævar Arnfjörð Bjarmason]

Change the SubmittingPatches recommendations to mention the 50
character soft limit on patch subject lines. 50 characters is the soft
limit mentioned in git-commit(1) and gittutorial(7), it's also the
point at which Gitweb, GitHub and various other Git front ends start
abbreviating the commit message.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/SubmittingPatches |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index eb53e06..099b238 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -7,7 +7,8 @@ Checklist (and a short version for the impatient):
 	  before committing
 	- do not check in commented out code or unneeded files
 	- the first line of the commit message should be a short
-	  description and should skip the full stop
+	  description (50 characters is the soft limit, see DISCUSSION
+	  in git-commit(1)), and should skip the full stop
 	- the body should provide a meaningful commit message, which:
 		- uses the imperative, present tense: "change",
 		  not "changed" or "changes".
-- 
1.7.0.4

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> Change the SubmittingPatches recommendations to mention the 50
> character soft limit on patch subject lines. 50 characters is the soft
> limit mentioned in git-commit(1) and gittutorial(7), it's also the
> point at which Gitweb, GitHub and various other Git front ends start
> abbreviating the commit message.

Hmph, we probably would want to do s/50 character/&s/ in the two manual
pages.  I do not think if anybody is ready to stand behind the specific
number "50", and we can bikeshed about it separately.

The spirit of having a soft limit is twofold:

 - It should fit on "git log --oneline" comfortably;

 - If your change is too complex to be summarized in such a short
   sentence, you probably are doing too many things in one commit.

The first does not justify "50" any better than other arbitrary limit, but
with things like --graph and --source, anything longer makes the resulting
output very close to the edge of an 80-column terminal.

The second does not justify "50" either, as your language may be verbose
or terse (e.g. Japanese can cram far more information in a 140-char tweet
than somebody writing in English), but it is a more important one between
the two rationales above.

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

[Ævar Arnfjörð Bjarmason]

On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com> wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> Change the SubmittingPatches recommendations to mention the 50
>> character soft limit on patch subject lines. 50 characters is the soft
>> limit mentioned in git-commit(1) and gittutorial(7), it's also the
>> point at which Gitweb, GitHub and various other Git front ends start
>> abbreviating the commit message.
>
> Hmph, we probably would want to do s/50 character/&s/ in the two manual
> pages.

I'm not sure if "with a single short (less than 50 character) line" is
is grammatically correct with "characters", since "characters line"
wouldn't make sense.

On the other hand that sentence violates the rule that when you put
something in parens your sentence should still make sense with
s/[()]//g, "a single short less than 50 character line" is pushing it.

I do not think if anybody is ready to stand behind the specific
> number "50", and we can bikeshed about it separately.
>
> The spirit of having a soft limit is twofold:
>
>  - It should fit on "git log --oneline" comfortably;
>
>  - If your change is too complex to be summarized in such a short
>   sentence, you probably are doing too many things in one commit.
>
> The first does not justify "50" any better than other arbitrary limit, but
> with things like --graph and --source, anything longer makes the resulting
> output very close to the edge of an 80-column terminal.
>
> The second does not justify "50" either, as your language may be verbose
> or terse (e.g. Japanese can cram far more information in a 140-char tweet
> than somebody writing in English), but it is a more important one between
> the two rationales above.

Right, 50 characters isn't magical. But I find it to be a really good
indicator that I'm going over the limit.

When I want to write something that's 60 characters or more that's
usually a sign that I should simplify the subject and just write a
more detailed body.

50 also fits neatly into interfaces where you want the summary and 2-3
other things on the page. Like in the Gitweb or Github interfaces.

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

[Joshua Juran]

On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:

> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com>  
> wrote:
>
>> Hmph, we probably would want to do s/50 character/&s/ in the two  
>> manual
>> pages.
>
> I'm not sure if "with a single short (less than 50 character) line" is
> is grammatically correct with "characters", since "characters line"
> wouldn't make sense.
>
> On the other hand that sentence violates the rule that when you put
> something in parens your sentence should still make sense with
> s/[()]//g, "a single short less than 50 character line" is pushing it.

If the number of characters is less than 50, then there are fewer than  
50 characters.

This is a short line of fewer than 50 characters.

Cheers,
Josh

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

[Ævar Arnfjörð Bjarmason]

On Wed, Jul 28, 2010 at 19:49, Joshua Juran <jjuran@gmail.com> wrote:
> On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:
>
>> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com> wrote:
>>
>>> Hmph, we probably would want to do s/50 character/&s/ in the two manual
>>> pages.
>>
>> I'm not sure if "with a single short (less than 50 character) line" is
>> is grammatically correct with "characters", since "characters line"
>> wouldn't make sense.
>>
>> On the other hand that sentence violates the rule that when you put
>> something in parens your sentence should still make sense with
>> s/[()]//g, "a single short less than 50 character line" is pushing it.
>
> If the number of characters is less than 50, then there are fewer than 50
> characters.
>
> This is a short line of fewer than 50 characters.

I don't understand the context of that remark or what you're replying
to.

I meant that I found the "single short (less than 50 character) line"
bit in git-commit.txt, gittutorial.txt and user-manual.txt odd to
read.

What did you mean?

Re: [PATCH] SubmittingPatches: Cite the 50 char subject limit

[Joshua Juran]

On Jul 28, 2010, at 1:15 PM, Ævar Arnfjörð Bjarmason wrote:

> On Wed, Jul 28, 2010 at 19:49, Joshua Juran <jjuran@gmail.com> wrote:
>> On Jul 28, 2010, at 12:25 PM, Ævar Arnfjörð Bjarmason wrote:
>>
>>> On Wed, Jul 28, 2010 at 17:23, Junio C Hamano <gitster@pobox.com>  
>>> wrote:
>>>
>>>> Hmph, we probably would want to do s/50 character/&s/ in the two  
>>>> manual
>>>> pages.
>>>
>>> I'm not sure if "with a single short (less than 50 character)  
>>> line" is
>>> is grammatically correct with "characters", since "characters line"
>>> wouldn't make sense.
>>>
>>> On the other hand that sentence violates the rule that when you put
>>> something in parens your sentence should still make sense with
>>> s/[()]//g, "a single short less than 50 character line" is pushing  
>>> it.
>>
>> If the number of characters is less than 50, then there are fewer  
>> than 50
>> characters.

This demonstrates the distinction between "less" and "fewer".   
Intensities (like raw numbers) and mass quantities are less; discrete  
objects are fewer.

>> This is a short line of fewer than 50 characters.

This demonstrates a grammatically correct way of phrasing a constraint  
on line length.  I could have put the latter half in parentheses, but  
then it wouldn't be true.  :-)

> I don't understand the context of that remark or what you're replying
> to.
>
> I meant that I found the "single short (less than 50 character) line"
> bit in git-commit.txt, gittutorial.txt and user-manual.txt odd to
> read.

Agreed.

> What did you mean?

See above.  You could also use "50-character" as an adjective, but  
"single short line (of fewer than 50 characters)" may be more easily  
parsed.  Another option is "single short line (shorter than 50  
characters)".  I find it less stilted without "of fewer", but the  
repetition of "short" is a little clumsy.

Josh