Thread: Commit subject line
Not sure if I mentioned this, but having first line of the commit be a subject has save me lots of time in writing the release notes. I know it is helpful to others too who browse our commits on websites. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On 05/03/2013 01:23 PM, Bruce Momjian wrote: > Not sure if I mentioned this, but having first line of the commit be a > subject has save me lots of time in writing the release notes. I know > it is helpful to others too who browse our commits on websites. > Yeah. The recommended style is to have the first line be 50 chars or less, which is a bit unfortunate - it can be a challenge to keep to that limit for a meaningful or comprehensive subject. cheers andrew
On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: > > On 05/03/2013 01:23 PM, Bruce Momjian wrote: > >Not sure if I mentioned this, but having first line of the commit be a > >subject has save me lots of time in writing the release notes. I know > >it is helpful to others too who browse our commits on websites. > > > > > Yeah. The recommended style is to have the first line be 50 chars or > less, which is a bit unfortunate - it can be a challenge to keep to > that limit for a meaningful or comprehensive subject. Yes, I know mine are often cut-off. What I just did was to add a 50-character dashed line to the top of my editor window for commits so I can see the limit each time --- that should help me. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On 03.05.2013 20:56, Bruce Momjian wrote: > On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >> >> On 05/03/2013 01:23 PM, Bruce Momjian wrote: >>> Not sure if I mentioned this, but having first line of the commit be a >>> subject has save me lots of time in writing the release notes. I know >>> it is helpful to others too who browse our commits on websites. >>> >> >> >> Yeah. The recommended style is to have the first line be 50 chars or >> less, which is a bit unfortunate - it can be a challenge to keep to >> that limit for a meaningful or comprehensive subject. > > Yes, I know mine are often cut-off. What I just did was to add a > 50-character dashed line to the top of my editor window for commits so I > can see the limit each time --- that should help me. Oh, that's tight. I didn't know about the 50 char recommendation. I've tried to keep mine < 76 chars, so that when you do "git log", it fits on a 80 char display with the 4 char indentation that git log does. - Heikki
On Fri, May 3, 2013 at 09:08:08PM +0300, Heikki Linnakangas wrote: > On 03.05.2013 20:56, Bruce Momjian wrote: > >On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: > >> > >>On 05/03/2013 01:23 PM, Bruce Momjian wrote: > >>>Not sure if I mentioned this, but having first line of the commit be a > >>>subject has save me lots of time in writing the release notes. I know > >>>it is helpful to others too who browse our commits on websites. > >>> > >> > >> > >>Yeah. The recommended style is to have the first line be 50 chars or > >>less, which is a bit unfortunate - it can be a challenge to keep to > >>that limit for a meaningful or comprehensive subject. > > > >Yes, I know mine are often cut-off. What I just did was to add a > >50-character dashed line to the top of my editor window for commits so I > >can see the limit each time --- that should help me. > > Oh, that's tight. I didn't know about the 50 char recommendation. > I've tried to keep mine < 76 chars, so that when you do "git log", > it fits on a 80 char display with the 4 char indentation that git > log does. Yes, I thought it was <80, but see lots of mine cut off on the website: http://git.postgresql.org/gitweb/?p=postgresql.git -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Heikki Linnakangas <hlinnakangas@vmware.com> writes:
> On 03.05.2013 20:56, Bruce Momjian wrote:
>> On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote:
>>> Yeah. The recommended style is to have the first line be 50 chars or
>>> less, which is a bit unfortunate - it can be a challenge to keep to
>>> that limit for a meaningful or comprehensive subject.
> Oh, that's tight. I didn't know about the 50 char recommendation. I've
> tried to keep mine < 76 chars, so that when you do "git log", it fits on
> a 80 char display with the 4 char indentation that git log does.
Yeah, that's news to me too. I've been using a 75-char line length for
all my commit messages since we switched to git. It's frequently tough
enough to get a useful headline into 75 chars --- I can't see trying to
do 50.
regards, tom lane
On 05/03/2013 01:56 PM, Bruce Momjian wrote: > On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >> On 05/03/2013 01:23 PM, Bruce Momjian wrote: >>> Not sure if I mentioned this, but having first line of the commit be a >>> subject has save me lots of time in writing the release notes. I know >>> it is helpful to others too who browse our commits on websites. >>> >> >> Yeah. The recommended style is to have the first line be 50 chars or >> less, which is a bit unfortunate - it can be a challenge to keep to >> that limit for a meaningful or comprehensive subject. > Yes, I know mine are often cut-off. What I just did was to add a > 50-character dashed line to the top of my editor window for commits so I > can see the limit each time --- that should help me. > vim does better than this. It color codes the characters so they change color after 50 chars in the first line. cheers andrew
On 05/03/2013 02:43 PM, Tom Lane wrote: > Heikki Linnakangas <hlinnakangas@vmware.com> writes: >> On 03.05.2013 20:56, Bruce Momjian wrote: >>> On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >>>> Yeah. The recommended style is to have the first line be 50 chars or >>>> less, which is a bit unfortunate - it can be a challenge to keep to >>>> that limit for a meaningful or comprehensive subject. >> Oh, that's tight. I didn't know about the 50 char recommendation. I've >> tried to keep mine < 76 chars, so that when you do "git log", it fits on >> a 80 char display with the 4 char indentation that git log does. > Yeah, that's news to me too. I've been using a 75-char line length for > all my commit messages since we switched to git. It's frequently tough > enough to get a useful headline into 75 chars --- I can't see trying to > do 50. man git-commit says: Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) linesummarizing the change, followed by a blank line and then a more thorough description. Tools that turn commits intoemail, for example, use the first line on the Subject: line and the rest of the commit in the body. I'd be happy to use 75 or whatever if we could convince the email tools not to truncate the subject lines at 50. cheers andrew
On 2013-05-03 14:54:23 -0400, Andrew Dunstan wrote: > > On 05/03/2013 02:43 PM, Tom Lane wrote: > >Heikki Linnakangas <hlinnakangas@vmware.com> writes: > >>On 03.05.2013 20:56, Bruce Momjian wrote: > >>>On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: > >>>>Yeah. The recommended style is to have the first line be 50 chars or > >>>>less, which is a bit unfortunate - it can be a challenge to keep to > >>>>that limit for a meaningful or comprehensive subject. > >>Oh, that's tight. I didn't know about the 50 char recommendation. I've > >>tried to keep mine < 76 chars, so that when you do "git log", it fits on > >>a 80 char display with the 4 char indentation that git log does. > >Yeah, that's news to me too. I've been using a 75-char line length for > >all my commit messages since we switched to git. It's frequently tough > >enough to get a useful headline into 75 chars --- I can't see trying to > >do 50. > > man git-commit says: > > Though not required, it’s a good idea to begin the commit message > with a single short (less than 50 character) line summarizing the > change, followed by a blank line and then a more thorough > description. Tools that turn commits into email, for example, use > the first line on the Subject: line and the rest of the commit in > the body. > > I'd be happy to use 75 or whatever if we could convince the email tools not > to truncate the subject lines at 50. Its worth to notice that neither git nor the kernel adhere to that limit... Greetings, Andres Freund -- Andres Freund http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training & Services
On Fri, May 3, 2013 at 7:54 PM, Andrew Dunstan <andrew@dunslane.net> wrote: > I'd be happy to use 75 or whatever if we could convince the email tools not > to truncate the subject lines at 50. Usually even truncated lines are still useful. Just try to avoid lines like This commit adds new code to implement a new feature to do xxx -- greg
On Fri, May 3, 2013 at 9:07 PM, Andres Freund <andres@2ndquadrant.com> wrote: > On 2013-05-03 14:54:23 -0400, Andrew Dunstan wrote: >> >> On 05/03/2013 02:43 PM, Tom Lane wrote: >> >Heikki Linnakangas <hlinnakangas@vmware.com> writes: >> >>On 03.05.2013 20:56, Bruce Momjian wrote: >> >>>On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >> >>>>Yeah. The recommended style is to have the first line be 50 chars or >> >>>>less, which is a bit unfortunate - it can be a challenge to keep to >> >>>>that limit for a meaningful or comprehensive subject. >> >>Oh, that's tight. I didn't know about the 50 char recommendation. I've >> >>tried to keep mine < 76 chars, so that when you do "git log", it fits on >> >>a 80 char display with the 4 char indentation that git log does. >> >Yeah, that's news to me too. I've been using a 75-char line length for >> >all my commit messages since we switched to git. It's frequently tough >> >enough to get a useful headline into 75 chars --- I can't see trying to >> >do 50. >> >> man git-commit says: >> >> Though not required, it’s a good idea to begin the commit message >> with a single short (less than 50 character) line summarizing the >> change, followed by a blank line and then a more thorough >> description. Tools that turn commits into email, for example, use >> the first line on the Subject: line and the rest of the commit in >> the body. >> >> I'd be happy to use 75 or whatever if we could convince the email tools not >> to truncate the subject lines at 50. > > Its worth to notice that neither git nor the kernel adhere to that > limit... FWIW, the tool we use to generate the commit emails truncate it at 80 (minus the "pgsql: " header). We can increase that, but it only fixes the email one, and not the one that people look at on the web... --Magnus HaganderMe: http://www.hagander.net/Work: http://www.redpill-linpro.com/
On 05/06/2013 10:19 AM, Magnus Hagander wrote: > On Fri, May 3, 2013 at 9:07 PM, Andres Freund <andres@2ndquadrant.com> wrote: >> On 2013-05-03 14:54:23 -0400, Andrew Dunstan wrote: >>> On 05/03/2013 02:43 PM, Tom Lane wrote: >>>> Heikki Linnakangas <hlinnakangas@vmware.com> writes: >>>>> On 03.05.2013 20:56, Bruce Momjian wrote: >>>>>> On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >>>>>>> Yeah. The recommended style is to have the first line be 50 chars or >>>>>>> less, which is a bit unfortunate - it can be a challenge to keep to >>>>>>> that limit for a meaningful or comprehensive subject. >>>>> Oh, that's tight. I didn't know about the 50 char recommendation. I've >>>>> tried to keep mine < 76 chars, so that when you do "git log", it fits on >>>>> a 80 char display with the 4 char indentation that git log does. >>>> Yeah, that's news to me too. I've been using a 75-char line length for >>>> all my commit messages since we switched to git. It's frequently tough >>>> enough to get a useful headline into 75 chars --- I can't see trying to >>>> do 50. >>> man git-commit says: >>> >>> Though not required, it’s a good idea to begin the commit message >>> with a single short (less than 50 character) line summarizing the >>> change, followed by a blank line and then a more thorough >>> description. Tools that turn commits into email, for example, use >>> the first line on the Subject: line and the rest of the commit in >>> the body. >>> >>> I'd be happy to use 75 or whatever if we could convince the email tools not >>> to truncate the subject lines at 50. >> Its worth to notice that neither git nor the kernel adhere to that >> limit... > FWIW, the tool we use to generate the commit emails truncate it at 80 > (minus the "pgsql: " header). We can increase that, but it only fixes > the email one, and not the one that people look at on the web... In practice, something else must be further truncating it, at about 64 chars by the look of it - see for example <http://www.postgresql.org/message-id/E1UVTFj-00079k-2r@gemulon.postgresql.org> Re your other point, github at least seems to elide at about 70 chars - see <https://github.com/postgres/postgres/commit/b42ea7981ce1e7484951a22662937541066d8647> - where Joe used a very long first sentence rather than a show summary line. I don't know if gitweb could be induced to elide after a greater length - I bet it could fairly easily. There does seem to be lots of spare screen real estate on the commit summary and history pages, which I think is where this occurs. cheers andrew
On Mon, May 6, 2013 at 4:47 PM, Andrew Dunstan <andrew@dunslane.net> wrote: > > On 05/06/2013 10:19 AM, Magnus Hagander wrote: >> >> On Fri, May 3, 2013 at 9:07 PM, Andres Freund <andres@2ndquadrant.com> >> wrote: >>> >>> On 2013-05-03 14:54:23 -0400, Andrew Dunstan wrote: >>>> >>>> On 05/03/2013 02:43 PM, Tom Lane wrote: >>>>> >>>>> Heikki Linnakangas <hlinnakangas@vmware.com> writes: >>>>>> >>>>>> On 03.05.2013 20:56, Bruce Momjian wrote: >>>>>>> >>>>>>> On Fri, May 3, 2013 at 01:42:33PM -0400, Andrew Dunstan wrote: >>>>>>>> >>>>>>>> Yeah. The recommended style is to have the first line be 50 chars or >>>>>>>> less, which is a bit unfortunate - it can be a challenge to keep to >>>>>>>> that limit for a meaningful or comprehensive subject. >>>>>> >>>>>> Oh, that's tight. I didn't know about the 50 char recommendation. I've >>>>>> tried to keep mine < 76 chars, so that when you do "git log", it fits >>>>>> on >>>>>> a 80 char display with the 4 char indentation that git log does. >>>>> >>>>> Yeah, that's news to me too. I've been using a 75-char line length for >>>>> all my commit messages since we switched to git. It's frequently tough >>>>> enough to get a useful headline into 75 chars --- I can't see trying to >>>>> do 50. >>>> >>>> man git-commit says: >>>> >>>> Though not required, it’s a good idea to begin the commit message >>>> with a single short (less than 50 character) line summarizing the >>>> change, followed by a blank line and then a more thorough >>>> description. Tools that turn commits into email, for example, use >>>> the first line on the Subject: line and the rest of the commit in >>>> the body. >>>> >>>> I'd be happy to use 75 or whatever if we could convince the email tools >>>> not >>>> to truncate the subject lines at 50. >>> >>> Its worth to notice that neither git nor the kernel adhere to that >>> limit... >> >> FWIW, the tool we use to generate the commit emails truncate it at 80 >> (minus the "pgsql: " header). We can increase that, but it only fixes >> the email one, and not the one that people look at on the web... > > > In practice, something else must be further truncating it, at about 64 chars > by the look of it - see for example > <http://www.postgresql.org/message-id/E1UVTFj-00079k-2r@gemulon.postgresql.org> Ha. Good point. There's actually a bit of a bug in the code there :) What it does is limit the length to 80-length("pgsql: $shortmsg"), which is 64. It is supposed to limit it to 80-length("pgsql: ").. (Since it substitutes the actual commit message where $shortmsg is found). That's fixable though :) > Re your other point, github at least seems to elide at about 70 chars - see > <https://github.com/postgres/postgres/commit/b42ea7981ce1e7484951a22662937541066d8647> > - where Joe used a very long first sentence rather than a show summary line. > I don't know if gitweb could be induced to elide after a greater length - I > bet it could fairly easily. There does seem to be lots of spare screen real > estate on the commit summary and history pages, which I think is where this > occurs. Possibly. I can never find my way around that one though, and making any modifications also has us ending up maintaining what's basically a fork - unless there's always a config argument for it somewhere. --Magnus HaganderMe: http://www.hagander.net/Work: http://www.redpill-linpro.com/
On Mon, May 6, 2013 at 06:41:53PM +0200, Magnus Hagander wrote: > > In practice, something else must be further truncating it, at about 64 chars > > by the look of it - see for example > > <http://www.postgresql.org/message-id/E1UVTFj-00079k-2r@gemulon.postgresql.org> > > Ha. Good point. There's actually a bit of a bug in the code there :) > What it does is limit the length to 80-length("pgsql: $shortmsg"), > which is 64. It is supposed to limit it to 80-length("pgsql: ").. > (Since it substitutes the actual commit message where $shortmsg is > found). > > That's fixable though :) > > > > Re your other point, github at least seems to elide at about 70 chars - see > > <https://github.com/postgres/postgres/commit/b42ea7981ce1e7484951a22662937541066d8647> > > - where Joe used a very long first sentence rather than a show summary line. > > I don't know if gitweb could be induced to elide after a greater length - I > > bet it could fairly easily. There does seem to be lots of spare screen real > > estate on the commit summary and history pages, which I think is where this > > occurs. > > Possibly. I can never find my way around that one though, and making > any modifications also has us ending up maintaining what's basically a > fork - unless there's always a config argument for it somewhere. So what should our goal length be? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On 06.05.2013 20:12, Bruce Momjian wrote: > On Mon, May 6, 2013 at 06:41:53PM +0200, Magnus Hagander wrote: > So what should our goal length be? Different tools seem to have different truncation points, so it sounds like the rule is something like: If you can keep it under 50 characters, great. If you can't, try to keep it below 70. But 75 at most. Or just "keep it as short as possible, but still meaningful". - Heikki