My point was more to the format (which I do find important), and I
think we should *also* encourage some syntax in addition to semantics.
It makes more sense for Differential to not care about those stuff
(since it's project-specific) that for any project that uses
Differential.
I think we should have both guidelines, content and syntax, but not
enforce or codify them.
We could reuse that content, but not link directly, as we can never
tell when that page changes and our assumptions may not change in the
same direction.
I agree that some unenforced syntax guidance is helpful. The first line length one should be particularly useful for me when I'm using Outlook Web Access which cuts off the subject line at 32 characters.
I think the only guideline we should have is that the first line should be written as though it is an email subject, because it gets used for that. If you write a long first line, then you get a long subject, and it looks silly. If people want to embarrass themselves with strangely formatted email, they it’s on them. We don’t need a specific hard or soft number.
Not many people care about the email subject already, that's why they
keep using ridiculously long first lines.
IMO, "suggesting" to write short first lines is the same as not doing
anything. Either we add a cap (say, 80 chars), or we don't do
anything.
Chandler's other suggestion, tough, is interesting: to write up a bit
about what a *good* message would be, so the people that were really
interested, could do it "right" (tm).
Another guideline I would like to propose for commit messages is that
of attaching to the commit a link to the code review, if any. For big
changes, this allows easily to reconstruct the history of the commit,
together with other informations (e.g. the reviewers). A potential
downside of it is that links might be not valid anymore after a while,
but I still think the advantages overcome the problems.
FWIW, I already try to include this info when I commit, so if it's not
OK or people have concerns about it, I would like to have this
explictly stated.
I think the only guideline we should have is that the first line should be
written as though it is an email subject, because it gets used for that. If
you write a long first line, then you get a long subject, and it looks
silly. If people want to embarrass themselves with strangely formatted
email, they it's on them. We don't need a specific hard or soft number.
Not many people care about the email subject already, that's why they
keep using ridiculously long first lines.
IMO, "suggesting" to write short first lines is the same as not doing
anything. Either we add a cap (say, 80 chars), or we don't do
anything.
Chandler's other suggestion, tough, is interesting: to write up a bit
about what a *good* message would be, so the people that were really
interested, could do it "right" (tm).
Another guideline I would like to propose for commit messages is that
of attaching to the commit a link to the code review, if any.
From: cfe-dev-bounces@cs.uiuc.edu [mailto:cfe-dev-bounces@cs.uiuc.edu] On
Behalf Of Renato Golin
Sent: Friday, March 06, 2015 1:13 PM
To: Reid Kleckner
Cc: Clang Dev; LLVM Dev
Subject: Re: [cfe-dev] [LLVMdev] Commit message policy?
> I think the only guideline we should have is that the first line should
be
> written as though it is an email subject, because it gets used for that.
If
> you write a long first line, then you get a long subject, and it looks
> silly. If people want to embarrass themselves with strangely formatted
> email, they it's on them. We don't need a specific hard or soft number.
Not many people care about the email subject already, that's why they
keep using ridiculously long first lines.
IMO, "suggesting" to write short first lines is the same as not doing
anything. Either we add a cap (say, 80 chars), or we don't do
anything.
Chandler's other suggestion, tough, is interesting: to write up a bit
about what a *good* message would be, so the people that were really
interested, could do it "right" (tm).
Renato,
Let me reflect this back to you, to make sure I understood it:
You don't like the idea of "suggesting" how to write a good message,
but you're okay with describing what a good message looks like? (as long
as we don't suggest that people should actually write them that way.)
--paulr
From: cfe-dev-bounces@cs.uiuc.edu [mailto:cfe-dev-bounces@cs.uiuc.edu] On
Behalf Of Mehdi Amini
Sent: Friday, March 06, 2015 1:49 PM
To: Davide Italiano
Cc: Clang Dev; LLVM Dev
Subject: Re: [cfe-dev] [LLVMdev] Commit message policy?
>
>>> I think the only guideline we should have is that the first line
should be
>>> written as though it is an email subject, because it gets used for
that. If
>>> you write a long first line, then you get a long subject, and it looks
>>> silly. If people want to embarrass themselves with strangely formatted
>>> email, they it's on them. We don't need a specific hard or soft
number.
>>
>> Not many people care about the email subject already, that's why they
>> keep using ridiculously long first lines.
>>
>> IMO, "suggesting" to write short first lines is the same as not doing
>> anything. Either we add a cap (say, 80 chars), or we don't do
>> anything.
>>
>> Chandler's other suggestion, tough, is interesting: to write up a bit
>> about what a *good* message would be, so the people that were really
>> interested, could do it "right" (tm).
>>
>
> Another guideline I would like to propose for commit messages is that
> of attaching to the commit a link to the code review, if any.
>
>> From: cfe-dev-bounces@cs.uiuc.edu [mailto:cfe-dev-bounces@cs.uiuc.edu]
On
>> Behalf Of Mehdi Amini
>> Sent: Friday, March 06, 2015 1:49 PM
>> To: Davide Italiano
>> Cc: Clang Dev; LLVM Dev
>> Subject: Re: [cfe-dev] [LLVMdev] Commit message policy?
>>
>>
>>>
>>>>> I think the only guideline we should have is that the first line
>> should be
>>>>> written as though it is an email subject, because it gets used for
>> that. If
>>>>> you write a long first line, then you get a long subject, and it
looks
>>>>> silly. If people want to embarrass themselves with strangely
formatted
>>>>> email, they it's on them. We don't need a specific hard or soft
>> number.
>>>>
>>>> Not many people care about the email subject already, that's why they
>>>> keep using ridiculously long first lines.
>>>>
>>>> IMO, "suggesting" to write short first lines is the same as not doing
>>>> anything. Either we add a cap (say, 80 chars), or we don't do
>>>> anything.
>>>>
>>>> Chandler's other suggestion, tough, is interesting: to write up a bit
>>>> about what a *good* message would be, so the people that were really
>>>> interested, could do it "right" (tm).
>>>>
>>>
>>> Another guideline I would like to propose for commit messages is that
>>> of attaching to the commit a link to the code review, if any.
>>
>> I believe it is documented here:
>> Code Reviews with Phabricator — LLVM 18.0.0git documentation
>>
>> Mehdi
>
> That would be the norm for people doing reviews in Phabricator.
> I think the suggestion is to do something similar for non-Phab reviews?
I really wish our mail web ui was better.... personally, I only use it as a
last resort. I'll turn first to my inbox, and then to gmane or marc.info or
any of the other mail archives.
As such, the most useful thing is for people to reply to review threads
with the revision at which the code landed. That way, I can find the commit
from the review thread (just the named revisions), or the review thread for
the commit (searching for the revision number turns up the review thread,
and also any relevant post-commit review or reference to it). The community
is actually pretty consistent about providing this and it's an awesome
system IMO.
I would vastly prefer we try to encourage this existing convention more
consistently, rather than trying to enforce putting links in commit
messages. The existing convention provides a bidirectional link.
I think the only guideline we should have is that the first line
should be written as though it is an email subject, because it gets
used for that. If you write a long first line, then you get a long
subject, and it looks silly. If people want to embarrass themselves
with strangely formatted email, they it's on them. We don't need a
specific hard or soft number.
Indeed; I agree that this is the most important thing, and that we don't need a specific character count so long as we explain that it becomes the subject of an e-mail. What prompted me to ping this thread was yet-another private e-mail exchange I had with a relatively-new contributor, where I pointed this out, and he or she hadn't realized or thought about it, and asked if we had this advice anywhere on the web site.
This part of the last-posted patch is also useful:
+* `Attribution of Changes`_ should be in a separate line, after the end of
+ the body, as simple as "Patch by John Doe.".
because I find standardization in this area comforting (and, more importantly, it will remind people to do it).
I know this is nitpicking, but do we want to specify the order between "Patch By" and "Differential Revision" for Phabricator reviews from people with no commit permissions?
(The Phabricator page says "the convention is for the commit message to end with the line...")
