On Aug 15, 2013, at 12:50 PM, Joe Gordon <joe.gord...@gmail.com> wrote:
> • > On Thu, Aug 15, 2013 at 12:22 PM, Sam Harwell <sam.harw...@rackspace.com> > wrote: > I like to take a different approach. If my commit message is going to take > more than a couple lines for people to understand the decisions I made, I go > and make an issue in the issue tracker before committing locally and then > reference that issue in the commit message. This helps in a few ways: > > > > 1. If I find a technical or grammatical error in the commit message, it > can be corrected. > > 2. Developers can provide feedback on the subject matter independently > of the implementation, as well as feedback on the implementation itself. > > 3. I like the ability to include formatting and hyperlinks in my > documentation of the commit. > > > > > This pattern has one slight issue, which is: > > • Do not assume the reviewer has access to external web services/site. > In 6 months time when someone is on a train/plane/coach/beach/pub > troubleshooting a problem & browsing GIT history, there is no guarantee they > will have access to the online bug tracker, or online blueprint documents. > The great step forward with distributed SCM is that you no longer need to be > "online" to have access to all information about the code repository. The > commit message should be totally self-contained, to maintain that benefit. I'm not sure I agree with this. It can't be true in all cases, so it can hardly be considered a rule. A guideline, maybe - something to strive for. But not all artifacts of the development process are amenable to being stuffed into code or the commits associated with them. A dvcs is great and all, but unless one is working in a silo, online resources are all but mandatory. m. > > > https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages > > > > > > Sam > > > > From: Christopher Yeoh [mailto:cbky...@gmail.com] > Sent: Thursday, August 15, 2013 7:12 AM > To: OpenStack Development Mailing List > Subject: Re: [openstack-dev] Code review study > > > > > > On Thu, Aug 15, 2013 at 11:42 AM, Robert Collins <robe...@robertcollins.net> > wrote: > > This may interest data-driven types here. > > https://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/ > > Note specifically the citation of 200-400 lines as the knee of the review > effectiveness curve: that's lower than I thought - I thought 200 was clearly > fine - but no. > > > > Very interesting article. One other point which I think is pretty relevant is > point 4 about getting authors to annotate the code better (and for those who > haven't read it, they don't mean comments in the code but separately) because > it results in the authors picking up more bugs before they even submit the > code. > > So I wonder if its worth asking people to write more detailed commit logs > which include some reasoning about why some of the more complex changes were > done in a certain way and not just what is implemented or fixed. As it is > many of the commit messages are often very succinct so I think it would help > on the review efficiency side too. > > > > Chris > > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
