My name is Jiange Sun and I'm a tester in Team Foundation Version Control (TFVC) team. I am responsible of testing add, checkin, delete/undelete, get and permission features. With this post, I'll provide an overview of checkin policies in TFVC.
The checkin policy provides a mechanism for an organization to define checkin rules for a team project and enforce them by the source control client during the checkin process. Checkin policies are implemented with the extensible checkin policy framework; third parties can implement their own checkin specific to their own application. Jim Presto has a post on how to implement a checkin policy.
We include 4 checkin policies in Visual Studio Team Foundation:
- Clean Build (Requires that code is error clean before check-in) Note: This one will go away after beta2 and be integrated in to “Code Analysis” policy
- Code Analysis (Requires that code analysis is run before check-in)
- Testing Policy (Requires run check-in tests before check-in)
- Work Items (Require that one or more work items be associated with every checkin.)
Next, I will be using the “Work Items” policy as an example to walk through a use case scenario.
Checkin policy Configuration
Let’s pretend that you are a Team Lead and you want your developers to associate at least one work item for their checkins. After multiple unsuccessful attempts on this message through team meetings and emails, you’ve had enough and decide to take advantage of the power of the checkin policy feature in Team Foundation:
1. You start VS, open the Team Explorer window.
2. On Team Explorer window, right click on your team project, select “Team Project Settings” | “Source Control …” from the context menu.
3. On Source Control Settings dialog, select the Checkin Policy tab.
4. Selects the “New…” button to define a new checkin policy:
5. Select Work Items and click on Ok:
Note: Checkin policies include a mechanism for providing instructions to the user in the event that the policy plugin is not installed on their system. Since the work item policy is included in our release and will be installed when you install Visual Studio Team System, the above dialog will go away after Beta2.
6. Click on Ok button. You see the newly added Work Items policy is showing in the list. You can also “Edit”, “Remove”, “Enable” and “Disable” a policy with a single button click on this dialog:
7. Click on Ok and that’s it. You’ve just finished configuring the Work Items checkin policy for your team project. Next let’s see how this policy is enforced automatically when your developers try to do a checkin without associating a work item.
Checkin policy Evaluation
Checkin policy evaluation process occurs during checkin process with the checkin dialog (both command line and VS). Let’s pretend that John Doe is a developer in your team and he is curious to see how the checkin policy you configured works:
a. John starts VS and opens the solution. He makes some changes in his code and is ready to check in. He right clicks on his solution in solution explorer and selects “Check in…” context menu.
b. John clicks on the “Check in” button and a “Policy Failure” dialog is presented since the Work Items checkin policy has not been satisfied:
Note: John really should’ve clicked on “Policy Warning” channel on the checkin dialog to see if all checkin policies are currently satisfied before he clicks on check in button. If John checks “Override policy failure and continue checkin”, the reason text box will be enabled and he can provide additional information about why he is checking in despite the policy failure. The Ok button is then enabled and the checkin will succeed if he clicks on it.
c. John clicks on the Cancel button on the “Policy Failure” dialog and he noticed that the checkin dialog has automatically switched to “Policy Warnings” channel for him. He sees the reason of the policy failure: “You must associate this checkin with one or more work items.”
d. John clicks on the “Work Items” channel on the “Check in” dialog and checks a work item. He then switches back to the Policy Warnings channel and now he sees a description that reads “All checkin policies are currently satisfied.”
e. John clicks on “Check in” button and this time it succeeds.
In this post, we looked at how to configure checkin policies, when checkin polices are evaluated and how to override a checkin policy failure. As you’ve seen, it’s pretty straightforward to use the new checkin policy feature in Visual Studio. Please let use know if you have any feedback on the checkin policy.
