Gary Haran.com

Writing bug reports is not an art form but a science. If you write bug reports for your team (and yes programmers should write some) here is a short list of what your report should do.

1. Tile of a bug report: describe with a subject and a verb

The title should be a clear and concise explanation of the problem. It should include a subject and a verb.

Bad: Saving does not work.
Good: Body field does not save on submit.

Don’t limit yourself to only subject and verb when the problem only occurs in some circumstances.

Better: Body field does not save on submit when using IE 7.

2. Body of a bug report: enumerate steps to reproduce

The body of the bug report should explain what steps lead to the problem. This means that anyone reading the bug report should be able to reproduce it using only the information in the report.

Bad: [empty body]
Bad: Field body does not save.
Good: I logged on with user madcoco and typed in the usual lorem ipsum in the body field. When I hit submit the “saving” message appeared but timed-out. When I hit refresh the rest of the form was saved but not the body field. This occured using Internet Explorer 7 but worked fine in Firefox 3.

Don’t forget that as you get more information you can always append more text to the body.

Better: John Doe from SkyNet tells me that he has the same error and it seems to be related to the latest Windows Update from Microsoft. This is a known issue as seen on http://www.ie-vista.com/known_issues.html

3. Body of a bug report: support the report with screenshot or screencast

The best bug report I received was a 22 second screencast. It arrived via email from a user who used some code of mine but was really bad at English. A screenshot might be all it takes but a video is the ultimate bug report.

Happy bug squashing!

Subversion is being phased out in favor of git so if you are just starting a project I recommend you hop on the git bandwagon right away. If you are stuck on svn though and need to branch and merge here’s a quick how-to.

Branching

svn cp https://myserver.dev/project/project_name/trunk https://myserver.dev/project/project_name/branches/branch_name
cd
svn co https://myserver.dev/project/projectname/branches/branch_name
cd branch_name

Now you can do your work in the branch as you would in trunk.

Merging To The Branch

Most people like to merge from trunk to the branch to make sure that tests still run. That way if you have to do a few various fixes you can do them step by step, each with their own checkin.

In order to do so in SVN you have to know what revision you merged at. This is tedious but there is a trick that the piston creator showed me.

Run this from the folder you have your branch checked out in.

svn log --stop-on-copy https://myserver.dev/project/projectname/branches/branch_name --revision HEAD:1

Logs will appear and you just have to remember the last revision number that appears. It is preceded by a lower case r. In my case it was r555 so 555 is the important number for me.

Now still in the same branch folder take that revision number and add it to this command:

svn merge -r 555:HEAD https://myserver.dev/project/project_name/trunk

Make sure that your tests run and if you have any conflict you have to manually edit the files to resolve them. Once everything is fine you can commit your changes to the branch.

svn commit -m "merged from trunk to branch"

Merging Back To Trunk

Now you have to go back to the folder where you edit your trunk. Here you must use the revision number you used earlier. The one that determines when you branched.

svn merge -r 555:HEAD https://myserver.dev/project/projectname/branches/branch_name

Hopefully you don’t have any conflicts but if you do open each conflicting files. Edit them to your liking and then use svn resolved filename. Finish up with a commit.

So that’s it. The good news for those of you stuck with SVN their next version will make this process slightly easier. Of course I hope that before they release the new version that you’ve joined the distributed wagon.

I’ve previously posted on how to to make Campfire less intrusive by using Growl but this one is even more fun. It takes whatever message in the room and speaks it for you using your default OS X voice.

@campfire_pass = 'enter_your_own_password'
@campfire_user = 'your@email.here'
@campfire_room = 'Main Room Or Whatever Name Room You Want'

require 'rubygems'
require 'tinder'

campfire = Tinder::Campfire.new 'standoutjobs'
campfire.login @campfire_user, @campfire_pass

campfire.find_room_by_name(@campfire_room).listen do |m|
  system("say \"#{m[:person]} says #{m[:message]}\"")
end

Season accordingly and have fun with it.

I’m headed to the unfortunately named event tonight where people having an interest in startups or entrepreneurship can meet up for a drink (and not where non-drinkers can take up drinking).

Send me a twit/shout/email if you’re going.

PS: you may have noticed that I caved in and am now using Twitter.