Re: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
On Fri, Aug 21, 2015 at 07:54:11PM -0400, David Malcolm wrote: > > >> In the git world, the first line of the commit message has special > > >> meaning, being treated as the "title" of the commit. > > > > > > It would be nice if we could use a real commit message, not just a short > > > title line; for example, people who prepare their patches in git already > > > have that, and use it with format-patch as you say. > > > > I think that's what David was suggesting; a short title line, followed > > by a blank line, followed by a more substantive commit message. > > > > This change doesn't need to be tied to the git transition; it could > > happen either before or after. > > Attached is a patch for the website which advises doing this when > committing. > +The log message for a checkin should be a single line giving a > +descriptive title for the checkin, followed by a blank line, followed by > +the complete ChangeLog entry for the change. This is the git convention; > +giving titles to checkins makes life easier for developers using git > +mirrors of SVN. Typically the descriptive title should be the "Subject" > +line of the relevant gcc-patches thread (without any "[PATCH]" or "[PING]" > +prefixes). It advises to *not* have an explanatory text, and it says that *not* having it is the Git convention (which of course is not true). Segher
Re: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
On Sat, 2015-08-22 at 05:55 -0500, Segher Boessenkool wrote: > On Fri, Aug 21, 2015 at 07:54:11PM -0400, David Malcolm wrote: > > > >> In the git world, the first line of the commit message has special > > > >> meaning, being treated as the "title" of the commit. > > > > > > > > It would be nice if we could use a real commit message, not just a short > > > > title line; for example, people who prepare their patches in git already > > > > have that, and use it with format-patch as you say. > > > > > > I think that's what David was suggesting; a short title line, followed > > > by a blank line, followed by a more substantive commit message. > > > > > > This change doesn't need to be tied to the git transition; it could > > > happen either before or after. > > > > Attached is a patch for the website which advises doing this when > > > > committing. I'm sorry that this was badly worded; "which" in the above was meant to refer to the patch, not the website. The purpose of the patch is to make a slight change to the policy (to add titles), as well as to document the new policy. > > +The log message for a checkin should be a single line giving a > > +descriptive title for the checkin, followed by a blank line, followed by > > +the complete ChangeLog entry for the change. This is the git convention; > > +giving titles to checkins makes life easier for developers using git > > +mirrors of SVN. Typically the descriptive title should be the "Subject" > > +line of the relevant gcc-patches thread (without any "[PATCH]" or "[PING]" > > +prefixes). > > It advises to *not* have an explanatory text, and it says that *not* > having it is the Git convention (which of course is not true). I'm having trouble parsing this. What did you mean by "it" in the three places you used it here? By "explanatory text", were you referring to the descriptive title, or to the text after the blank line? (I haven't had my coffee yet this morning, so my apologies if I'm misreading things...) Dave
Re: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
On Sat, Aug 22, 2015 at 10:59:31AM -0400, David Malcolm wrote: > > > +The log message for a checkin should be a single line giving a > > > +descriptive title for the checkin, followed by a blank line, followed by > > > +the complete ChangeLog entry for the change. This is the git convention; > > > +giving titles to checkins makes life easier for developers using git > > > +mirrors of SVN. Typically the descriptive title should be the "Subject" > > > +line of the relevant gcc-patches thread (without any "[PATCH]" or > > > "[PING]" > > > +prefixes). > > > > It advises to *not* have an explanatory text, and it says that *not* > > having it is the Git convention (which of course is not true). > > I'm having trouble parsing this. What did you mean by "it" in the three > places you used it here? By "explanatory text", were you referring to > the descriptive title, or to the text after the blank line? Heh, sorry. First two "it"s refer to your patch / the new text; last "it" refers to "explanatory text" earlier in the sentence. Your suggested text says that commit messages should be a title, and a blank line, immediately followed by a changelog. It (that is, your suggested text) says you shouldn't put anything useful in the commit message, like what the commit is all about. Segher
Re: [PATCH][www] svnwrite.html: recommend giving checkin messages a title (was Re: Moving to git)
* David Malcolm: > +The log message for a checkin should be a single line giving a > +descriptive title for the checkin, followed by a blank line, followed by > +the complete ChangeLog entry for the change. This is the git convention; > +giving titles to checkins makes life easier for developers using git > +mirrors of SVN. Typically the descriptive title should be the "Subject" > +line of the relevant gcc-patches thread (without any "[PATCH]" or "[PING]" > +prefixes). For glibc, we often try to put the reason for the change in the commit message. Especially for code deletions, you can't really add a comment to the sources, and official policy is that you must not put explanations into the ChangeLog file (it's just a mechanical description of the change). So giving an explanation *somewhere* is often nice, and the commit message is a good place for that.
