Dec 4, 2007

A Check In Checklist

Team based software development projects usually give a lot of thought to what source control repository to use (TFS, Subversion, CVS, BitKeeper, etc), how/when they should branch their code, what they do with coding standards, etc.  Yet at the same time not a lot of attention is given to the art of the check in.  Most teams assume that a check in is just a matter of clicking the check in/commit changes button and that's it.

As a result many teams often run afoul of check ins gone wrong and time and again find themselves rolling back changes or fighting with each other over why a change was done or constantly falling back to the "it works on my machine" line when the changes they make break a whole bunch of other things in the app.  And usually this happens during crunch time when everyone is trying to finish up their work before a deadline.

In an effort to prevent this happening, below is a potential check in checklist you might want to use as a basis for helping your team improve the way they commit code to the source repository.  The most important thing to note is that it's not the steps themselves that result in good check ins, but rather it's the team thinking about what they're doing and sweating the details of each change before committing.

So, here's the checklist:

 

Pre Check In

Before any check in occurs make sure that you have done a code review and run all of your unit tests (not just the ones that touch on your code changes).  You should also make sure that you have covered the following:

1. Retrieved the latest code from the source repository [for the entire project, not just the area you are working on] and merged any changes

2. If you work against local copies of databases, ensure that your database schema's are up to date

3. Make sure your code compiles (it might sound obvious but you'd be surprised how often this step is skipped on small changes or after a merge from step 1)

4. Make sure ALL unit tests pass.

5. If you have functional tests or other build verification tests (BVT’s) make sure they pass as well

6. Ensure all code is commented appropriately

7. Any UI changes have been communicated to testers as appropriate

8. Any solution changes have been communicated to the build master (if you have one)

 

Check In

Do NOT check in anything if the Continuous Integration build is broken (with the exception of check ins to specifically fix breaks).  This will help ensure that the effort put into fixing a broken build is not stymied by a moving code base.

When checking in, write appropriate comments.  The first line of a check in comment is used as a title in many source control systems so it's good habit to write comments using multiple lines where possible.

Check in all files whenever possible and do the check in from the root.  This will help ensure that you don’t miss files in the check in process, which is a common occurrence when checking in from a sub-folder.  Also, if you have a file checked out that you don’t need anymore then undo/revert your changes so that you don’t have masses of files with pending changes hanging around.  Having many files in this state makes it easy to either miss a file you want checked in or to incorrectly commit a file you didn't want to change.

If you use CI builds and daily builds try to avoid doing check ins right before the daily build kicks off.  If the CI build breaks you want to make sure you have time to fix any problems that may arise before the daily build starts (why break 2 builds right?).

SPECIAL CASE: Large Check Ins.  When doing a large check in try and do it first thing in the morning.  That way if it breaks the build you will have enough time to fix things during the day.

 

Post Check In

If you use Continuous Integration then after doing a check in DON’T GO ANYWHERE. Don’t leave for the day, don’t go to lunch and don’t rush off to a meeting. You’re not done yet!  You need to make sure that your CI build succeeds.

If you use TFS you can open up Team Explorer and select the Team Builds.  Choose the “All Build Types” entry (or your CI build type) and double click it.

clip_image002

Watch that the CI build starts (typically about 1 minute after check in) and watch/wait until it completes successfully.  This image shows a build in progress.

clip_image004

If it all succeeds then you're sweet and can go do what ever else you had in mind.  If it breaks then it's your responsibility to figure out what went wrong.

 

Diagnosis

If you did break the build, you can double click the build in Team Explorer and have a look to see if the break was specifically related to your changes.

If you use CC.NET you can view the build details from the web dashboard (either by opening it up manually or double clicking the build from CCTray)

What was Included?

It’s often useful to know what was actually included in the build.  To find out, go to the bottom of the summary and click the highlighted link

clip_image006

After you click the [+] you’ll then see all the changesets since the last successful build, with the latest ones shown at the bottom. Clicking the links will show you what was in the changeset and may give you a clue as to what else might have snuck into the build that you weren't aware of.

If you are using CruiseControl.NET all the revisions in the build are usually shown at the top of the build summary.

Test Failures

Test failures are usually easy to spot.  You should see something like this:

clip_image012

Look down further and open up the Details view (click the [+])

clip_image014

To see which test run(s) failed.  You can also click the failing test run to get the individual test results.  Find the failing test(s)

clip_image018

And double click it to see what the details are and take action from there.

Under CruiseControl.NET the test summary is usually shown on the summary page, and you then have to click the NUnit Results on the left of the page to see the details.  The NUnit list will then show which tests failed, and by drilling down you can typically see the test failure reasons.

Compilation Failures

These are easy to diagnose and usually relate to people forgetting to include new files in the check in process.  A compilation problem will bomb out the build before testing starts

In TFS look down at the bottom the build summary and click the build details as shown

clip_image022

This will open a text file with just the errors and warnings from the build, and it's a lot smaller than the full build log so it's much easier to spot the problem.  Have a look for the error and take action as appropriate.

Under CruiseControl.NET you will usually see compilation errors on the build summary, however further details can be found within the the detailed build log itself.  In a CC.NET environment, a compilation failure will also mean that the usual NUnit & FxCop information won't get shown on the summary page - these sections will either be blank or missing.

 

I hope this is useful for you and gives you a starting point for your own teams.

1 comment:

  1. Great post! I like all the examples and screenshots -- makes it very easy to follow.

    On the subject of checklists, I recently published an article on CM Crossroads about how to build and update practical checklists.

    Also, although I'm biased by the fact that our company makes a peer code review tool, I wrote a free book about code review that doesn't hype our tool. Did I mention it's free?

    It's nice to see people talking more and more about how to do code reviews in a practical way. Thanks!

    ReplyDelete