Making the most of your source control summaries
Posted at 08:00 on 17 March 2009
The summary for Django's changeset number 9756 caught my attention recently:
Fixed #8138 -- Changed django.test.TestCase to rollback tests (when the database supports it) instead of flushing and reloading the database. This can substantially reduce the time it takes to run large test suites.
This change may be slightly backwards incompatible, if existing tests need to test transactional behavior, or if they rely on invalid assumptions or a specific test case ordering. For the first case, django.test.TransactionTestCase should be used. TransactionTestCase is also a quick fix to get around test case errors revealed by the new rollback approach, but a better long-term fix is to correct the test case. See the testing doc for full details.
Many thanks to:
* Marc Remolt for the initial proposal and implementation.
* Luke Plant for initial testing and improving the implementation.
* Ramiro Morales for feedback and help with tracking down a mysterious PostgreSQL issue.
* Eric Holscher for feedback regarding the effect of the change on the Ellington testsuite.
* Russell Keith-Magee for guidance and feedback from beginning to end.
Before I came across this particular essay (via Eric Holscher and Simon Willison), like most developers, I only ever put a short one-sentence summary in my source control commits. It had never occurred to me to do anything else -- in fact when Trac lists the changes in your repository, it only displays the first line anyway. Some developers don't even do that, instead leaving the summary blank altogether.
But hey, I thought -- why not? Why shouldn't we write a whole two paragraphs to add a bit more detail to our descriptions of our source control commits? After all, something short and simple may be OK when you're the only developer working on a project, but when you're working as part of a team, you need to keep the communication up.
You see, suppose that one day you are testing some code that you have been working on and you discover that it is barfing. So you scratch your head for a bit, step through it in the debugger, and so on, and you narrow it down to one particular line of code. You look at the revision logs and you find that I was the one who checked in the offending code. You'll probably be upset with me, but if I have given a decent explanation of what I've done when I check in my changes to source control, it will make the situation a lot easier for all concerned.
So don't just gloss over your source control summaries: make the most of them. You'll be doing all your colleagues a massive favour if you do.