{"thread":{"id":"29101","subject":"How to make devs write better commit messages","startedAt":"2011-12-06T22:55:07Z","lastAt":"2011-12-07T07:06:09Z","messageCount":5,"participants":["Joseph Huttner","Michael Schubert","Hilco Wijbenga","Junio C Hamano","Thomas Koch"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"180427","messageId":"CAOJsP-X0ZWT5HLHcBc2FmhoMpWFOvEFADiM9jGZ9R1ctqHDJ9w@mail.gmail.com","threadId":"29101","inReplyTo":null,"subject":"How to make devs write better commit messages","fromName":"Joseph Huttner","fromEmail":"huttnified@gmail.com","sentAt":"2011-12-06T22:55:07Z","receivedAt":"2011-12-06T22:55:07Z","isPatch":false,"sender":{"key":"huttnified@gmail.com","avatar":null},"body":"So I know that there is a somewhat standard format of commit messages\nin Git, which Linus outlines here:\n\nhttps://github.com/torvalds/subsurface/blob/master/README#L164\n\nTrouble is, when most people go to commit, the file that the editor\nopens has no reminder of how to write a proper commit message.  Often\nI find myself having to go back through the commit log, or consulting\nthe above link.\n\nI propose two things:\n\n1.  An optional flag in the Git config that, if set, shows the format\nof a typical commit message in your commit message template.\n\n2.  The ability to modify this commit message template.  Many teams\nuse automated tools to read commit messages and then do automated\ntasks based on that data, like comment an RT ticket.  Thus, developers\nneed to be reminded of these team-specific settings as well.\n\nWhat are your thoughts?\n\nThe bottom line is that good commit messages are really important, so\nwe should make it as easy as possible for developers to go ahead and\nwrite a perfect commit message every time they commit code.\n\n\nE.g.\n\n\n# Please enter the commit message for your changes. Lines starting\n# with '#' will be ignored, and an empty message aborts the commit\n# On branch master\n# Changes to be committed:\n#   (use \"git reset HEAD <file>...\" to unstage)\n#\n# modified:   application/views/layouts/layout.phtml\n#\n# Untracked files:\n#   (use \"git add <file>...\" to include in what will be committed)\n#\n# public/js/databases/\n#\n# How to properly format your commit message:\n#\n# \tHeader line: explaining the commit in one line\n#\n#\tBody of commit message is a few lines of text, explaining things\n#\tin more detail, possibly giving some background about the issue\n#\tbeing fixed, etc etc.\n#\n#\tThe body of the commit message can be several paragraphs, and\n#\tplease do proper word-wrap and keep columns shorter than about\n#\t74 characters or so. That way \"git log\" will show things\n#\tnicely even when it's indented.\n#\n#\tRT: 123, 456 [a comma-separated list of RT tickets this commit refers to]\n#\n"},{"id":"180430","messageId":"4EDEA2E2.3030002@elegosoft.com","threadId":"29101","inReplyTo":"CAOJsP-X0ZWT5HLHcBc2FmhoMpWFOvEFADiM9jGZ9R1ctqHDJ9w@mail.gmail.com","subject":"Re: How to make devs write better commit messages","fromName":"Michael Schubert","fromEmail":"mschub@elegosoft.com","sentAt":"2011-12-06T23:18:58Z","receivedAt":"2011-12-06T23:18:58Z","isPatch":false,"sender":{"key":"mschub@elegosoft.com","avatar":null},"body":"On 12/06/2011 11:55 PM, Joseph Huttner wrote:\n> So I know that there is a somewhat standard format of commit messages\n> in Git, which Linus outlines here:\n> \n> https://github.com/torvalds/subsurface/blob/master/README#L164\n> \n> Trouble is, when most people go to commit, the file that the editor\n> opens has no reminder of how to write a proper commit message.  Often\n> I find myself having to go back through the commit log, or consulting\n> the above link.\n> \n> I propose two things:\n> \n> 1.  An optional flag in the Git config that, if set, shows the format\n> of a typical commit message in your commit message template.\n> \n> 2.  The ability to modify this commit message template.  Many teams\n> use automated tools to read commit messages and then do automated\n> tasks based on that data, like comment an RT ticket.  Thus, developers\n> need to be reminded of these team-specific settings as well.\n> \n> What are your thoughts?\n\nIf it's no social issue but just due to lack of a reminder you\ncould provide a template for commit.template. Either way: you\nstill would have to force people to set it.?\n"},{"id":"180432","messageId":"CAE1pOi3REHvQjrO+=K+qt5dH60U+Le4Ty_Vq2nFPpWS27h1+Eg@mail.gmail.com","threadId":"29101","inReplyTo":"CAOJsP-X0ZWT5HLHcBc2FmhoMpWFOvEFADiM9jGZ9R1ctqHDJ9w@mail.gmail.com","subject":"Re: How to make devs write better commit messages","fromName":"Hilco Wijbenga","fromEmail":"hilco.wijbenga@gmail.com","sentAt":"2011-12-07T00:08:35Z","receivedAt":"2011-12-07T00:08:35Z","isPatch":false,"sender":{"key":"hilco.wijbenga@gmail.com","avatar":null},"body":"On 6 December 2011 14:55, Joseph Huttner <huttnified@gmail.com> wrote:\n> So I know that there is a somewhat standard format of commit messages\n> in Git, which Linus outlines here:\n>\n> https://github.com/torvalds/subsurface/blob/master/README#L164\n>\n> Trouble is, when most people go to commit, the file that the editor\n> opens has no reminder of how to write a proper commit message.  Often\n> I find myself having to go back through the commit log, or consulting\n> the above link.\n>\n> I propose two things:\n>\n> 1.  An optional flag in the Git config that, if set, shows the format\n> of a typical commit message in your commit message template.\n>\n> 2.  The ability to modify this commit message template.  Many teams\n> use automated tools to read commit messages and then do automated\n> tasks based on that data, like comment an RT ticket.  Thus, developers\n> need to be reminded of these team-specific settings as well.\n>\n> What are your thoughts?\n\nGreat idea! These templates would be stored in the Git repo, I assume?\nBtw, there is 'commit.template' which you can use locally.\n\n I was wondering if it might be possible to somehow add project config\ndefaults to one's Git repo. It would be great to have something like\n'commit.template' point to a file in the Git repo by default.\nCurrently, it doesn't seem possible to have a config parameter \"point\nto\" a file or directory in the Git repo. Nor do I know of a way to\nhave the Git repo set a config parameter to a default value. Or is\nthis possible after all?\n"},{"id":"180440","messageId":"7vaa75cdzi.fsf@alter.siamese.dyndns.org","threadId":"29101","inReplyTo":"4EDEA2E2.3030002@elegosoft.com","subject":"Re: How to make devs write better commit messages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-12-07T02:28:01Z","receivedAt":"2011-12-07T02:28:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael Schubert <mschub@elegosoft.com> writes:\n\n>> What are your thoughts?\n>\n> If it's no social issue but just due to lack of a reminder you\n> could provide a template for commit.template. Either way: you\n> still would have to force people to set it.?\n\nWhile that would be a good first step, I think people will learn best when\nthey feel by their skin how good log messages help them in the long run.\n\nPick a recent bugfix in your project, analyze why the code was broken by\nthe bug in the first place, and view the log message of the commit that\nintroduced the code that was broken by the buggy commit. You will often\nnotice that the original commit did not explain why the code needs to be\nthat way sufficiently, risking later breakage, and the buggy commit that\nbroke the code did not justify the change any more than \"This happens to\nmake something work for me in a particular narrow case\".\n\nAnd then look at the log message of the bugfix. Does it explain why the\nbroken change was bad, and the fixed code _has to be_ that way?\n\nDo this for a handful of examples, and you will start noticing patterns,\nand what makes good messages that become useful in the longer term. Have\nyour people learn from good ones _as well as_ the bad ones.\n\nHave fun.\n"},{"id":"180460","messageId":"201112070806.09539.thomas@koch.ro","threadId":"29101","inReplyTo":"CAOJsP-X0ZWT5HLHcBc2FmhoMpWFOvEFADiM9jGZ9R1ctqHDJ9w@mail.gmail.com","subject":"Re: How to make devs write better commit messages","fromName":"Thomas Koch","fromEmail":"thomas@koch.ro","sentAt":"2011-12-07T07:06:09Z","receivedAt":"2011-12-07T07:06:09Z","isPatch":false,"sender":{"key":"thomas@koch.ro","avatar":null},"body":"Joseph Huttner:\n> The bottom line is that good commit messages are really important, so\n> we should make it as easy as possible for developers to go ahead and\n> write a perfect commit message every time they commit code.\n\nI recently started to work with the code review system Gerrit[1]. First I did \nnot pay attention to it, but later I was amazed that the commit message can \n(and should) be reviewed just like the code changes.\n\nSo if you're using a code review prozess (you should!) then also include the \ncommit message in the review.\n\n[1] http://en.wikipedia.org/wiki/Gerrit_%28software%29\n\nThomas Koch, http://www.koch.ro\n"}]}