Alec,
Thanks for posting this. I'm +1 on all of it, with a few comments below.
On Aug 29, 2005, at 11:30 AM, Alec Flett wrote: Folks -
I'm coming back from vacation and trying to catch up on whats been going on.. its been a trying experience to say the least :)
The tools I'm using to catch up are:
1) reading bugmail
2) looking at checkin logs
3) reading dev (of course!)
This opened up a host of issues that I think we need to discuss.
This is an open source project and if we ever want real involvement from the rest of the community beyond lurkers on the mailing list, we've got to make it easier to follow and track changes to the project. Yes, the weekly updates are very helpful, and we've been good about posting to [email protected]. However once you dive in and start hacking code, you need to be able to track the history of specific bugs or specific checkins. There are about a hundred other reasons to create a electronic paper trail of your work, but I'll just start with that one :)
Below I've listed a few proposed guidelines that I believe every single one of us needs to follow.
Bugzilla
The bug system is the way that QA can verify that a problem has been fixed or not, and what issues to look out for when a bug is resolved. It is also the next entry point after a prospective developer (or new OSAF employee) starts investigating chandler.
I'd disagree that the bug system is this far upstream in for new developers, but that's probably just a reflection of cultural differences between Apache and Mozilla. I completely agree that keeping the bug system as useful as possible is very important.
Here are some suggested guidelines:
1) Read your bugmail. Don't just delete it, or set up your preferences never to receive it. Users may make comments in bugs asking for clarification, or may even offer to help. If you don't read the bugmail, you won't ever know this is happening and it will appear that our project is unresponsive to new developers.
1a) If you get too much bugmail, go make your bugzilla email pref matrix at (https://bugzilla.osafoundation.org/userprefs.cgi?tab=email) match mine at http://www.flett.org/chandler/magicbuglist.html
2) When you mark a bug FIXED, add a comment to the bug explaining how it was fixed or at least resolved. Bonus points if you include the SVN revision. I'm going to talk to heikki about requiring you to type something when you mark a bug FIXED.
3) Try, TRY to document your work even as you make progress on a bug. Think of bugzilla as your own personally bug-by-bug blog. I personally try to make daily updates even if my progress is slow:
"I've added the basic Trash management code but the spec has some holes. I'll talk to Sheila and Mimi about the following cases that I'm confused about"
We have a bad practice in the project of sending "private" (i.e. not to dev@ or any other public place) e-mail when working on bugs (or even whole branches). It would be much much better to have these kinds of discussions being recorded either in bugzilla or in e-mail.
I remember hearing that we were looking at a patch to bugzilla that would allow updating a bug via e-mail instead of the web form. I for one would be very interested in having this capability.
Checkins
The checkin logs are useful for multiple reasons - not the least of which is "blame" (see http://websvn.osafoundation.org/blame.php?repname=chandler&path=%2Ftrunk%2Fchandler%2FChandler.py&rev=0&sc=0) for an example) If I see what is I think a typo on a line, or need to know WHY a particular section of the code looks the way it does, I use blame - but it relies on the checkin comments actually being accurate and thorough.
The three questions you should answer in every checkin are "What?" "How?" and "Why?"
- What behavior/code am I changing? (Often the bug number alone can be enough for this)
- How am I changing it or solving the problem?
- Why am I trying to solve it?
Maybe this seems excessive, but this can be as simple as "Changed result of GetMessageStatus to True so that messages actually get sent, as per bug 19395"
There are of course exceptions to this, such as a branch landing, but even those comments should include the bug number that refers to the branch landing work. Other exceptions may be removal of dead code, etc, bug at least explain that in your checkin comment.
A few examples of comments (you know who you are :)) that are completely unhelpful.. imagine going back and looking at these checkins in 6 months and trying to figure out what the heck was going on:
- "Fix typo in Collection"
- "oops"
- "fix tinderbox"
Ow. Guilty as charged. /me raps his own knuckles with a ruler....
I hereby grant permission for people to remind me when I'm not doing the stuff in this message. I promise to (gently) do the same.
Ted |
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
