Welcome to the Hotel Team Foundation

So, this has been awhile coming. Let's blame that on the combination of 2 zillion screenshots and the lovely weather we've been having.

You can check in any time you like, but you can never leave.

Well, actually, you can only check in if the tree isn't currently locked, you have the right permissions, and the files you're trying to check in don't have any conflicts to resolve. But that's another story, and you can read up on those issues at the linked posts.

In our last episode, we left the Pending Changes on the verge of becoming a great and mighty Changeset, just as the mere acorn may one day become a mighty oak. First, however, they have to survive the rigors of the checkin process.

Back in August, Jim posted on this very subject. However, I'd like to give you a visual guide to what that process actually looks like, aided by my ever handy Alt-PrintScreen.

The checkin dialog has four "channels", each related to a different subset of the checkin process. These are "Source Files", "Work Items", "Checkin Notes", and "Policy Warnings". We join our story already in progress at the Source Files channel.

A Jedi's power flows from the source file*

I felt a great disturbance in the source, as if a millions of files pended changes, and were suddenly checked in.

Let's begin with our illuminating screenshot. Heck, why not make it two for good measure. The difference, of course, is that the first shows the flat view while the second shows tree view. But wait, that's not all you get with this incredible one time offer! Order now, and you can also hide the comment field like so.

Breaking this down, we see four buttons along the left side, several buttons along the top, and then the comment field and the files themselves. We also have the "Check In" button and the "Cancel" button. The left pane lets you switch between the four different checkin channels. See how "Source Files" is currently highlighted? In the the rest of the screenshots, you'll see the appropriate button highlighted to help our viewers at home stay on the same page.

Along the top, the buttons are: "Toggle comment pane", "Tree view", "Flat view", "Compare", "Open", "Undo", "Refresh", and "Sort". From the "Pending Changes" dialog, which is a non-modal tool window, we also have"Shelve" and "Unshelve". In order of appearance:

• Toggle comment pane: Sadly, I have nothing clever to add here, besides pointing up at the previously mentioned image.
• Tree View and Flat view: These switch the current view of the lower right pane between the two views shown above.
• Compare: If the file selected is not being added, you can compare it with previous versions, the workspace version, and the latest version.
• Open: Opens the selected file or folder.
• Undo: This button lets you undo a pending change and revert the selected file(s) to version you last got from the repository.
• Refresh: Useful for refreshing the contents of the dialog if you have another Visual Studio or command line opened and have pended or undone changes there.
• Sort: While you can sort by clicking on the column headings, this button opens a dialog that provides both an accessible sorting mechanism (i.e. it doesn't require the mouse), and a more comprehensive control like that seen in Work Item tracking.
• Shelve and Unshelve: Available in the non-modal tool window. Shelve the current pending changes (or some subset thereof) or restore previously shelved changes. Much more on what this actually means can be found here.

The guts of this channel, of course, is the comment and the source files themselves. After all, without files to edit, we wouldn't have any pending changes to begin with and the whole concept of version control would be rather odd. The comment field is a standard, multi-line text field that is intended to briefly describe the current changes.

As for files, you can decide to select only some of your pending changes, as we see here, to help group similar changes. In the folder view, you can select or deselect and entire folder wholesale. You can also collapse the folders once you're done playing around with the check boxes. Eventually, though, you have to move on, as exciting as checkboxes can be.

Also, the context menu in the file list lets you view the local version, compare against previous/workspace/lasest verion, undo, refresh the checkin window, and get the properties of a file.

Onward and upward, then, to the Work Item channel.

Tracking the illusive Work Item

G'day, mate, and welcome. T'day, we'll be tracking all manner o' work items, from the simple task to the pesky bug. Hope y' brought along yer bug spray! Crikey, if not, you'll be a goner fer sure!

Once this pane loads, you have to select a work item query. Selecting the query will populate the work item area as seen here. In this shot, we've associated with two work items, one of which will be closed when we check in.

We can choose any project or private query from which to select work items. For example, if the team has a query called "v1.0 Work Items", you can select that. If you have your own query called "My Favorite Bugs", you can select that, instead. Once you choose a query, you can select one or more work items and decide whether to simply associate them with the current checkin or to fully resolve the work item. The important take home lesson here is that the changeset to work item mapping is a many to many mapping. Each changeset can be associated with multiple work items, and each work item can be associated with multiple changesets. This helps us track progress over time as well as the impact of each individual changeset.

Passing Checkin Notes in class

Now Johnny, if it's important enough to pass in class, why don't you come up here and read it out loud to all of us?

Some team projects don't have any checkin notes. Others do. "Wow!" you're thinking, "It's like magic! He pulled those checkin notes right out of his hat." Actually, I'm not wearing a hat. I am, however, meddling in the Version Control Settings dialog. (To get there in the December CTP, right-click on a team project, select "Team Project Settings", "Source Control", and then click the "Checkin Notes" tab. Abra cadabra!)

When setting up checkin notes, some can be required while others are optional. Checkin notes are simple text fields that help further clarify a checkin. For example, we require users of the system to specify a code reviewer before they can check in. We can also choose to have them specify a test review, security reviewer, performance reviewer, customer impact, favorite color, mother's maiden name, and average flight speed velocity of an unladen swallow. Which is quite silly-- everyone knows African swallows are non-migratory.

There is no "Satisfy" in "Policy", but that doesn't make you exempt

Complete policy satisfaction guaranteed or your pending changes back

Checkin policies are a whole different can of worms. Luckily, we can turn again to our friend Jim for a marvelous introduction, as well as two posts on writing your own policies.

For our purposes, though, we'll take a screen shot of a checkin that satisfies all policies (either because there are none or it has satisfied all that qualify), as well as one that fails. If a policy fails, you can still check in, but are required to enter a comment explaining why. Do beware, though, that administrators of the team project get notifications when policies are overridden (and, if they wish, anytime someone checks in anything at all). Luckily, Jeff recently posted on Team Foundation Alerts.

And that's the long and short of it! In our next episode, we'll learn about changesets and where they fit into the system.

Before Star Wars© fans the world over jump all over me, I'm aware it's actually the Force. I hope you'll find it in your hearts to forgive me this time.