[Dev] better checkin comments

[Alec Flett]

I'd like to make a request that people write more elaborate checkin comments - its incredibly frustrating to read the commits list and see stuff like "fixed two bugs in calendar" - I don't know about you folks, but I use the commits list to learn about new parts of the codebase... (A brief, hopefully humorous rant: I mean, why even make a checkin comment if you're not going to describe what you checked in? Why not say "Checked in a file" or "Used SVN to combine the changes I made with the code in our source repository" or even "Wrote some Python"? I kid!) The checkin guidelines (http://wiki.osafoundation.org/twiki/bin/view/Chandler/CheckinRules) say, in no uncertain terms: Write a meaningful comment for your checkin, and mention the bug number (if any) and code reviewer (if any) in the comments. Here's an example: "Bug 1234, fixed memory leak with repository delete, r=heikki." Personally, I like to say: 1) WHAT changed in the code - i.e. a highlevel description of the actual behavioral change in the code 2) WHY I made the change - who cares? is this really necessary? 3) What bug # it fixes, if any. Here are a few examples of what I thought were good checkin comments: pje: Schema API: Ensure that the repository's core schema is *fully* initialized by the time any items need to be created in a given view. bear: Enabling long running tests when the CHANDLER_PERFORMANCE_TEST environment variable is defined. Also populated __init__.py so run_tests.py can be used to run the sharing tests. What's great is that with each of these, I can read the checkin comment on the commits list, or read the comment on websvn. (http://websvn.osafoundation.org/log.php?repname=chandler&path=%2F&rev=0&sc=0&isdir=1) or read it in cvsblame, .. and then learn something about a new part of the codebase. Thoughts? feedback? discussion?

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev