Wednesday, April 23, 2008

Bug Reports

It turns out many people really struggle with writing bug reports. What I'm going to recommend here is exactly the same thing you'll find in the Joel on Software article, Painless Bug Tracking.

What I've found is if you go to someone and say, "What's the bug?", they'll have no problem describing it to you. But when they write the bug report, it comes out all confusing.

The difference is when I asked them "What's the bug?", they were happy to describe the bug to me. But when I ask them to report it, they feel like they need to tell me what the bug IS. Subtle difference, but it has a large effect. The result is typically a mangled sentence or two about how something didn't work. But it doesn't clearly tell me what they were doing or what they expected or even in what way it didn't work. Its like they are suddenly afraid to give me the context in which they found the bug.

So how do you write a bug report?
Just tell me these three things:
  1. Steps to reproduce the bug
  2. What should have happened
  3. What happened instead
  4. Provide extra details (exception text, error message screen shot, stack trace, etc)
The fun part about this is for many people they will save both time AND keystrokes reporting bugs this way because they no longer have to stress about "How do I communicate this bug?!"

For example,
1. Go to this form
2. Click on the "S'Okay" button
Error box should pop up, but instead the app crashes.

Crash report: blah blah blah blah blah...

You can use this method to report any kind of bug, you will save yourself time writing it, and you will save time trying to figure out what the bug is and how to fix it. Everyone wins, everyone is happy.

Sunday, April 6, 2008

TFS Source Control

The source control system that comes with TFS is pretty good. It's absolutely fantastic when compared with Visual Source Safe (what was so Visual about it anyway?).

It has "Path Space Branching," meaning you can create branches by creating new folders. It follows the Checkout, Edit, Merge pattern by default, meaning many developers can work on the same file at the same time (no locks). It integrates beautifully with Visual Studio, and all of its dialogs and wizards are really straight forward and intuitive.

That said, it is not without its issues...

Anyone who has ever tried to organize a branching strategy for an office of developers knows that branches add complexity, and complexity adds confusion, and confusion slows stuff down. On the other hand, the isolation that branches provide can make life much easier for individuals and individual teams as well as the whole office. This is mainly because you can focus on developing new stuff and not worry about breaking other people or integrating you changes until you're done. Sounds minor, but its a huge help.

However, once you're using branches in this way, you're making the majority of your changes on the "development" branches and then merging back to the "public" branches when you want to release your changes. Enter TFS issue #1.

Merges result in a single changeset, they do not reproduce all the changesets made on the source branch on the target branch.

This means, if you have 5 changesets on your dev branch, with associated checkin comments, and work item associations, and user identification, NONE of that information will appear on the target branch. So when you're trying to figure out:
  1. Who made this change?
  2. When did this change?
  3. What has changed recently?
you. are. screwed.

In my opinion, this is so severe it almost makes branches in TFS completely worthless.

But wait, there's more! TFS has branches, and TFS integrates really well with Visual Studio, but its not as perfect as it seems...

Using branches can screw up your project and solution files

It all looks like it should work well. You've got your references set up as project references. You branch everything and the relative paths are all setup the same (..\..\myproject). And yet, somehow VS still gets confused. You start getting errors where the version numbers arn't right. Or it wants to check out all your project and solution files. It's terribly annoying.

And what happens if the relative paths arn't the same? In the branching environment we've setup this happens in some scenarios because branch our project's shared dependencies into the same directory as the main project to isolate the project from all outside changes. When you do this, you have to completely rebuild your project references and solution files because VS gets confused. This isn't the end of the world, but it is a huge annoyance.

It also means, any time you perform a merge, you have to merge the project files by hand because VS will think there are changes (the relative paths) even though there aren't any real changes.

Ready for the next issue?

There is no simple way to rollback a changeset.

The TFS power tools comes with a rollback command, but it's command line only and it's not terribly easy to use (since you need to know the changeset numbers). The absence of this feature in the GUI proper just makes no sense. This is one of those features people always use to sell why you should be using a Version Control system, and TFS doesn't even have it.

I should stop and mention that these are the downsides. The rest of the Version Control that I've used is really great. Workspaces are cool, though only moderately useful. And Shelves are a decent concept, though again, only moderately useful.

The funny part about branching is that when you learn about distributed source control systems, your first reaction is, that would never work, and your second reaction is, that's perfect! Many of the problems you were trying to solve with branching just go away and get replaced with simple communication problems. As in, you have to tell other people when they should pull from you and that kind of thing. However, there are no distributed systems that I currently know of that integrate with Visual Studio like TFS's source control does, nor that are nearly as user friendly. However, I would still encourage you to check them out as it will give you a whole new perspective on versioning.