Folks, After looking at git / svn logs for a long time today, I realised that the commit messages could be a bit more helpful for that purpose (logs). The kernel has a good policy on commit messages, and I think we could use some of that, at least as a strong guideline, not as a hard rule. The idea, AFAIK, is to have a title with 50 chars, separated by an empty line and an infinite number of 80-col lines following. That allows us to be very descriptive on the context, but succinct enough on the title, so that logs can fit on a reasonably sized terminal + git ids, etc. Is that something we want to follow? I could only find the attribution rule on the developer's policy (which we should definitely keep), but would be good to have at least some policy on the commit message itself. Also, policies for messages when reverting patches, arc commits, approval lists would be good to have documented, rather than keep replying to people on the list. cheers, --renato PS: I don't want us to revert patches with non-standard messages, only encourage people to do it right.
On Wed, Sep 24, 2014 at 3:51 PM, Renato Golin <renato.golin at linaro.org> wrote:> Folks, > > After looking at git / svn logs for a long time today, I realised that > the commit messages could be a bit more helpful for that purpose > (logs). The kernel has a good policy on commit messages, and I think > we could use some of that, at least as a strong guideline, not as a > hard rule. > > The idea, AFAIK, is to have a title with 50 chars, separated by an > empty line and an infinite number of 80-col lines following.I've never enforced a particular character limit on the first line, but I try to make sure it's one line, then a blank line, then the rest - this ensures that one line is the subject of the email sent to the mailing list. A lot of people end up wrapping their summary line to 2 or 3 lines, which results in an email subject (& as you mention, git/svn log summaries, etc) that contain only a sentence fragment that might not be meaningful. I think git log summaries don't mind really long initial lines - the tools will wrap it, so far as I know.> That > allows us to be very descriptive on the context, but succinct enough > on the title, so that logs can fit on a reasonably sized terminal + > git ids, etc. > > Is that something we want to follow? I could only find the attribution > rule on the developer's policy (which we should definitely keep), but > would be good to have at least some policy on the commit message > itself. > > Also, policies for messages when reverting patches, arc commits, > approval lists would be good to have documented, rather than keep > replying to people on the list. > > cheers, > --renato > > PS: I don't want us to revert patches with non-standard messages, only > encourage people to do it right. > _______________________________________________ > cfe-dev mailing list > cfe-dev at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20140924/992a6af5/attachment.html>
On 24 September 2014 15:51, Renato Golin <renato.golin at linaro.org> wrote:> The idea, AFAIK, is to have a title with 50 chars, separated by an > empty line and an infinite number of 80-col lines following.I tend to follow something like that anyway so I think it's a good idea, but if anything I'd prefer a longer title line than the body. Particularly with the prefixes we tend to put in there, 50 chars is hardly anything. Cheers. Tim.
On 24 September 2014 23:59, David Blaikie <dblaikie at gmail.com> wrote:> I've never enforced a particular character limit on the first line, but I > try to make sure it's one line, then a blank line, then the rest - this > ensures that one line is the subject of the email sent to the mailing list.Vim is really useful for that, as it colours the first 50 chars of the title, so you know when you passed the limit.> I think git log summaries don't mind really long initial lines - the tools > will wrap it, so far as I know.They do, but it messes up the formatting. I agree, that's not a really bad thing... cheers, --renato
On Wed, Sep 24, 2014 at 4:03 PM, Tim Northover <t.p.northover at gmail.com> wrote:> On 24 September 2014 15:51, Renato Golin <renato.golin at linaro.org> wrote: > > The idea, AFAIK, is to have a title with 50 chars, separated by an > > empty line and an infinite number of 80-col lines following. > > I tend to follow something like that anyway so I think it's a good > idea, but if anything I'd prefer a longer title line than the body. > Particularly with the prefixes we tend to put in there, 50 chars is > hardly anything. >Yep, that's my main concern about imposing a (quite short) limit on the summary line.> > Cheers. > > Tim. > _______________________________________________ > cfe-dev mailing list > cfe-dev at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20140924/6de33813/attachment.html>
On 25 September 2014 00:03, Tim Northover <t.p.northover at gmail.com> wrote:> I tend to follow something like that anyway so I think it's a good > idea, but if anything I'd prefer a longer title line than the body. > Particularly with the prefixes we tend to put in there, 50 chars is > hardly anything.I only mentioned 50-col because that's what Vim helps me do automatically. :) I'm fine with larger titles, but not larger than 70-col, which should be plenty, since we don't have complex branching in git. GMail can cope with up to 90 chars (+preamble) in the subject. cheers, --renato
On 9/24/14 5:03 PM, Tim Northover wrote:> On 24 September 2014 15:51, Renato Golin <renato.golin at linaro.org> wrote: >> The idea, AFAIK, is to have a title with 50 chars, separated by an >> empty line and an infinite number of 80-col lines following. > > I tend to follow something like that anyway so I think it's a good > idea, but if anything I'd prefer a longer title line than the body. > Particularly with the prefixes we tend to put in there, 50 chars is > hardly anything.I tend to look at this like I look at superExtremelyLongFunctionNames: if it needs a really long description for the summary, maybe it's better to break it into a few smaller patches. My $0.02, anyway... :) Cheers, Jon> > Cheers. > > Tim. > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-- Jon Roelofs jonathan at codesourcery.com CodeSourcery / Mentor Embedded
+1 for a having a short leading sentence followed by a blank line. This is always the email subject, so plan accordingly. IMO the rest doesn't matter and isn't worth codifying. On Wed, Sep 24, 2014 at 3:51 PM, Renato Golin <renato.golin at linaro.org> wrote:> Folks, > > After looking at git / svn logs for a long time today, I realised that > the commit messages could be a bit more helpful for that purpose > (logs). The kernel has a good policy on commit messages, and I think > we could use some of that, at least as a strong guideline, not as a > hard rule. > > The idea, AFAIK, is to have a title with 50 chars, separated by an > empty line and an infinite number of 80-col lines following. That > allows us to be very descriptive on the context, but succinct enough > on the title, so that logs can fit on a reasonably sized terminal + > git ids, etc. > > Is that something we want to follow? I could only find the attribution > rule on the developer's policy (which we should definitely keep), but > would be good to have at least some policy on the commit message > itself. > > Also, policies for messages when reverting patches, arc commits, > approval lists would be good to have documented, rather than keep > replying to people on the list. > > cheers, > --renato > > PS: I don't want us to revert patches with non-standard messages, only > encourage people to do it right. > _______________________________________________ > cfe-dev mailing list > cfe-dev at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20140924/7e84e9ad/attachment.html>
On Wed, Sep 24, 2014 at 4:49 PM, Reid Kleckner <rnk at google.com> wrote:> +1 for a having a short leading sentence followed by a blank line. This is > always the email subject, so plan accordingly. > > IMO the rest doesn't matter and isn't worth codifying. >IMO, none of this is worth codifying really... We could certainly have a little guide for how to write awesome commit logs and point people at it. But this is one of (many) aspects of getting ramped up on the practices and patterns of the community. Not sure it ever really makes sense to try to codify so much as explain it... -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20140924/c03f1a41/attachment.html>