[Building Sakai] Commit messages - a humble little plea

[D. Stuart Freeman]

On Wed, Feb 15, 2012 at 10:11:37AM -0500, Zhen Qian wrote:
> I agree with the plea and I will remember to include more context and change info into the commit log.
> 
> However, I think there is another exception to this, the security jiras. I think the succinct text like just the jira number is enough for those, since the log text is public.

So is the changeset though, so if it's obvious that it's a security issue
an attacker can presumably work out the attack based on the new logic.

> 
> Thanks,
> 
> - zhen
> 
> On Feb 14, 2012, at 5:51 PM, Steve Swinsburg wrote:
> 
> > I agree with this, trunk commits should include info about what the commit is doing. However there is one exception, branch merging. 
> > 
> > These have historically been of the form:
> > 
> > SAK-123 merge trunk r12345
> > 
> > If it merges cleanly, otherwise it would be:
> > 
> > SAK-123 manually merge trunk r12345 (and any other notes required).
> > 
> > You can then reference the original trunk commit and jira.
> > 
> > cheers,
> > Steve
> > 
> > 
> > On 15/02/2012, at 4:25 AM, DAVID ROLDAN MARTINEZ wrote:
> > 
> >> I absolutely agree. In fact, my commit messages are so brief (just the ticket number) because I thought that was the standard way of doing this. :D
> >> 
> >> -----Mensaje original-----
> >> De: sakai-dev-bounces at collab.sakaiproject.org [mailto:sakai-dev-bounces at collab.sakaiproject.org] En nombre de Aaron Zeckoski
> >> Enviado el: martes, 14 de febrero de 2012 18:14
> >> Para: Noah Botimer
> >> CC: sakai-dev
> >> Asunto: Re: [Building Sakai] Commit messages - a humble little plea
> >> 
> >> Definitely agree with this. And as much as possible, try to include the intent/reason behind the commit rather than just repeating the title which is probably something weird like "Tool X instructions are confusing". A better message would be "Updated the tool X instructions with more details about using a mouse in a web browser".
> >> 
> >> -AZ
> >> 
> >> 
> >> On Tue, Feb 14, 2012 at 11:56 AM, Noah Botimer <botimer at umich.edu> wrote:
> >>> Hello folks,
> >>> 
> >>> A trend I've noticed is the shortening of commit messages, to the 
> >>> point of simply being a JIRA issue number. There is an up-side here: I 
> >>> don't remember the last real commit I saw without a JIRA ticket 
> >>> referenced. However, the downside is significant in assuming that this is sufficient.
> >>> 
> >>> Take, for example, examining the history of a couple of branches to 
> >>> find when something was introduced. Common cases of this are 
> >>> cherry-picking a feature and porting a bug fix. I won't belabor all of 
> >>> the hassle, but mention a few points:
> >>> 
> >>> First, each JIRA ticket must be called up individually to see what the 
> >>> intent was (set aside the topic of issue titles, which could be better 
> >>> generally). Second, there are often multiple commits against a ticket, 
> >>> sometimes interleaved with others, so the task often includes closely 
> >>> analyzing multiple diffs just to divine the intent. Third, there are 
> >>> occasionally errors in the reference or multiple issues combined in a 
> >>> commit, making it very difficult to track in either direction (from 
> >>> JIRA or Subversion).
> >>> 
> >>> 
> >>> So, my simple request follows:
> >>> 
> >>> Could we please try to include a brief summary of what action is being 
> >>> taken with each commit? If the change is non-trivial, please also 
> >>> include some details of what was introduced, changed, or removed.
> >>> 
> >>> 
> >>> JIRA is great, but the one real truth is the source revision history. 
> >>> If you are committing something, please tell the historical record 
> >>> what you were doing.
> >>> 
> >>> Although it has some Git specifics, this is a very nice
> >>> guideline: 
> >>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> >>> 
> >>> Thanks,
> >>> -Noah
> >>> 
> >>> 
> >>> _______________________________________________
> >>> sakai-dev mailing list
> >>> sakai-dev at collab.sakaiproject.org
> >>> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
> >>> 
> >>> TO UNSUBSCRIBE: send email to 
> >>> sakai-dev-unsubscribe at collab.sakaiproject.org
> >>> with a subject of "unsubscribe"
> >> 
> >> 
> >> 
> >> --
> >> Aaron Zeckoski - Software Architect - http://tinyurl.com/azprofile _______________________________________________
> >> sakai-dev mailing list
> >> sakai-dev at collab.sakaiproject.org
> >> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
> >> 
> >> TO UNSUBSCRIBE: send email to sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"
> >> _______________________________________________
> >> sakai-dev mailing list
> >> sakai-dev at collab.sakaiproject.org
> >> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
> >> 
> >> TO UNSUBSCRIBE: send email to sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"
> > 
> > _______________________________________________
> > sakai-dev mailing list
> > sakai-dev at collab.sakaiproject.org
> > http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
> > 
> > TO UNSUBSCRIBE: send email to sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"
> > 
> > 
> 
> _______________________________________________
> sakai-dev mailing list
> sakai-dev at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
> 
> TO UNSUBSCRIBE: send email to sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"

-- 
D. Stuart Freeman
Georgia Institute of Technology
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
Url : http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20120216/74270814/attachment.bin