Walkthrough: Customizing Check-in Policies and Notes

Visual Studio Team Foundation Server allows you to create a custom check-in, including:

  • Creating Check-in Notes Templates and Requirements

    You can define your own fields for collecting check-in related information and that require certain pieces of information be specified by users during the check-in process. This information, similar to a check-in comment, is persisted with other changeset details and included in the e-mail that is delivered to other team members.

  • Defining Check-in Policies

    You can define custom check-in rules to enforce restrictions upon the types of changes that can be committed to the source control server. For example, a project administrator can define rules to validate source changes prior to committing them to the server. Team Foundation ships with check-in policies for validating that work items are associated with changes, unit tests pass successfully, and static analysis has run cleanly on source code. These policies are extensible via a plug-in model so that you can enforce requirements of a different kind simply by creating a new policy plug-in. The check-in policies that are applied to your team project will depend on which MSF process is used by the team project. For more information, see Finding and Using Process Guidance.

This walkthrough describes how to add check-in notes and how to define a check-in policy that requires work items be associated with every check-in.

Required Permissions

To complete this walkthrough, you must have the Check out and Edit server-level information permissions set to Allow. For more information, see Team Foundation Server Permissions.

Creating Check-in Notes

In Visual Studio Team Foundation Server, you can define your own fields for your team's check-in notes and establish user requirements for the check-in process at the level of root folders in the server (for example, $/folder1). These folders correspond to your team projects. Those settings then apply to all source contained under those folders. When users attempt to check in revisions to a server folder for which custom check-in notes or requirements are defined, they are prompted to complete the notes in the Check In dialog box or Check In window. Check-in notes can be optional or required, however the only validation that occurs on required notes is that the length of the specified text is greater than zero.

To add and configure a check-in note

  1. From Team Explorer, right-click your team project, choose Team Project Settings, and then choose Source Control.

    The Source Control Settings dialog box appears.

  2. Click the Check-in Notes tab and then click Add.

    The Add Check-in Note dialog box appears.

  3. In the drop-down list box for Name, type the name that you want to use for the new check-in note; for example, "Doc Impact" for your documentation team.

  4. Optionally, select Required on check-ins and then click Add.

    This makes adding text for this check-in note mandatory during the check-in process.

  5. Optionally, change the order of the check-in notes by selecting a check-in note and using the arrow buttons to move its placement order.

  6. When you are satisfied with the settings for the check-in notes, click OK.

    The new check-in note now displays with future check-ins.

To see your new check-in notes, check out and edit a file from a properly-configured root-level folder, and then check in your revision at the command prompt. Selecting the "check-in notes" channel on the Check In dialog box should reveal your custom fields.

Defining Check-in Policies

To further customize check-ins, you can define check-in policies that evaluate compliance of changes with organizational standards.

To define a new check-in policy

  1. From Team Explorer, right-click your team project, choose Team Project Settings, and then choose Source Control.

    The Source Control Settings dialog box appears.

  2. Click the Check-in Policy tab and then click Add.

    The Add Check-in Policy dialog box appears.

  3. In the list box under Check-in Policy, select the desired policy type, Code Analysis, Testing Policy or Work Items, and click OK.

    If you selected Code Analysis, the Code Analysis Policy Editor appears.

  4. Click all the rules you want to specify, and then click OK.

    If you selected Testing Policy, the Testing Policy dialog box appears.

  5. Click Browse to specify a metadata file, select the test desired, and then click OK.

    If you selected Work Items, the Work Items policy type is added to the Source Control Settings dialog box.

  6. When you are satisfied with the settings for the check-in policies, click OK.

    The new check-in policy now displays with future check-ins.

To see the check-in policy, check out and edit a file from the folder for which you just defined it, and then check in your revision using the Check In dialog box or Pending Changes window in Visual Studio. Alternatively, you can type tf checkin at the command prompt.

Selecting the Policy Warnings channel in the dialog box or tool window displays a message indicating whether your changes are compliant with the defined check-in policies. If you have not selected any work items on the Work Items channel, you see a message indicating that you are not in compliance with policy. To satisfy policy, change to the Work Item channel and select a work item for association with your change. Alternatively, you can continue to check in without complying with policy. If you do so, you will be prompted to explain why you have overridden the check-in policy.

Creating Policy Plug-ins

You can create custom policy plug-ins that appear in the Add Checkin Policy dialog box by using the extensibility provided in the Visual Studio Team Foundation Server SDK. The Visual Studio Team Foundation Server SDK is available for download at https://go.microsoft.com/fwlink/?linkid=68586 as a part of Visual Studio SDK. For more information on policy plug-ins, search the Visual Studio SDK Help after you have installed the SDK.

See Also

Tasks

Walkthrough: Exploring Team Foundation Source Control

Reference

Add Command

Other Resources

Team Foundation Source Control Walkthroughs