[Building Sakai] Commit messages - a humble little plea

[Zhen Qian]

Ahh, I guess that's the beauty of opensource then :)

svn is designed to never lose information. I don't know whether svn is capable to hide content diff or log message, aka "confidential checkin", based on security settings.

How about git? Just curious.

Tanks,
- Zhen
On Feb 16, 2012, at 11:54 AM, D. Stuart Freeman wrote:

> 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