How To Template

From Guidance Share

Jump to: navigation, search

Contents

Template

  • Title
  • Applies To
  • Summary
  • Contents
  • Objectives
  • Overview
  • Step 1. Do This.
  • Stpe 2. Do That.
  • Step 3. Do This.
  • Related Items
  • Additional Resources


Test Cases

Title

Test Cases:

  • Does the title distinguish by product or version where possible?
  • Are important nouns a user might scan for towards the left of the title?
  • Does the title effectively convey what the how to is addressing?


Applies To

Test Cases:

  • Is it clear what technologies or products this applies to?
  • Conversely, is it clear what technologies of products this does not apply to?


Overview

Test Cases:

  • Does the overview provide enough background information to understand why it is necessary to take the steps?
  • Does the overview provide enough information that the module can stand alone?


Summary of Steps

Test Cases:

  • Will the set of steps listed solve the problem?


Step <<N>>

Test Cases:

  • Does each step explain what to do, why it is important and then how to take action?
  • If there is a decision point is it called out with an explicit ‘if…’ condition?
  • Is the How To capable of standing alone without requiring the user to search elsewhere to complete the solution?
  • Where appropriate, are there code or configuration file examples?


Considerations

Test Cases:

  • Are the consequences of applying this How To considered?
  • Are potential solutions to these consequences outlined?
  • Has testing, security, performance, reliability and operations been considered?


Additional Resources

Test Cases:

  • For each link, do you know why the link is included without first following the link?
  • Are the links from trusted sites?
  • Are the links correct in context of the How to?


Related Items

Test Cases:

  • Are the correct items linked in context of the How to?


Example

How To: Perform a Baseless Merge in Team Foundation Server

- J.D. Meier, Jason Taylor, Alex Mackman, Prashant Bansode


Applies To

  • Team Foundation Server
  • Visual Studio Team System


Summary

This How To shows you how to merge files from two branches that are not related to one another. The process of merging items that are not directly branched from each other is called a baseless merge. To perform a baseless merge, you must use the Tf merge command. You cannot perform a baseless merge operation from Visual Studio.


Contents

  • Objectives
  • Overview
  • Summary of Steps
  • Step 1. Evaluate if a baseless merge is needed
  • Step 2. Perform a baseless merge by using Tf.exe
  • Step 3. Resolve merge conflicts
  • Step 4. Check-in the merged changes
  • Additional Resources


Objectives

Learn how to do a baseless merge


Overview

In this how to you learn to do a baseless merge. The process of merging items that are not directly branched from each other is called a baseless merge. For example, you might want to merge a change between two release branches, which are siblings of each other, without merging up to the parent branch. You can only perform a baseless merge by using the Tf.exe command line utility. You cannot perform a baseless merge from Visual Studio.


When you perform a baseless merge Team Foundation Server does not have any information about the relationship of the files in the branches. For example, if you have renamed a file, this will be viewed as a deleted file and a new file in the branch. For this reason you have to perform more manual conflict resolutions than when you perform a normal merge. However, you only have to perform this conflict resolution once. After you have performed the baseless merge, Team Foundation Server records history and establishes a relationship between the folders and files.


Summary of Steps

  • Step 1. Evaluate if a baseless merge is needed
  • Step 2. Perform a baseless merge by using Trif.exe
  • Step 3. Resolve merge conflicts
  • Step 4. Check-in the merged changes


Step 1. Evaluate if a Baseless Merge Is Needed

In this step you evaluate the branches and items to be merged to determine if you need to do a baseless merge or whether a regular merge will work.


If you are owner / administrator of your team project you will know the relationships of the branches or items. You can only merge from Visual Studio the branches or items which have a parent-child relationship. If your project contains branches or items which do not have this relationship, you require a baseless merge.


If you are not aware of all the relationships of the branches or items, you can evaluate if you need to use a baseless merge as follows.


  • Open Source Code Explorer.
  • Right-click the branched folder and click Merge.
  • In the Source Control Merge Wizard dialog box, look under the drop down for Target branch.
  • If you do not see an entry for the branch you want to merge it indicates that no merge relationship exists between these branches. In this case you must perform a baseless merge.


Step 2. Perform a Baseless Merge By Using Tf.exe

In this step you use the Team Foundation Server command line tool Tf.exe to perform a baseless merge.

To perform a baseless merge:

  • Set the Workspace for both branches by performing a get latest operation on the branches to be merged.
  • Open Source Code Explorer.
  • Right-click the folder for the first branch to be merged and click Get Latest Version.
  • Repeat the previous step for the second branch to be merged.


Note that if you do not have a workspace mapped Visual Studio prompts you to select a folder on your local drive.


  • Open a Visual Studio Command Window.
  • Run the following Tf.exe command from the command line.
Tf merge /baseless <<source path>> <<target path>> /recursive

Example

Tf merge /baseless c:\data\proj1 c:\data proj2 /recursive 


If you need to merge specific versions of the code changes you can use the version switch with Tf.exe as follows

tf merge /baseless <<source path>> <<target path>> / recursive /version:<<from Changeset>>~<<to Changeset>> 

Example

tf merge /baseless c:\data\proj1 c:\data\proj2 /recursive /version:C123~C125


Step 3. Resolve Merge Conflicts

In this step you resolve conflicts that might occur when performing a baseless merge. Once you have run the Tf.exe command it display a Resolve Conflicts dialog box with a list of the files with conflicts.


To resolve merge conflicts


  • Select each file and click Resolve.
  • In the Resolve version conflict dialog box, if there are no content changes choose the Keep changes in the target branch resolution option and click OK.
  • If there are content changes, select Merge changes in merge tool resolution option and click OK.
  • In the merge tool click the conflict regions in the upper panes or type in the lower pane to apply change for each conflicting line.
  • Once you have applied changes for all the conflicts, click OK in the merge tool.
  • Once all the conflicts are resolved click Close.


Step 4. Check-in the Merged Changes

In this step you check-in the baseless merged changes

To check-in merged changes:

  • Open Source Code Explorer.
  • Right-click the target folder in which you have merged the changes and click Check-in pending changes.
  • In the Check-In Source Files dialog box, ensure that all the files to be checked in are selected.
  • Click Check In.


Additional Resources

For more information about other merging options please see Merge CommandTeam Foundation Server Branching Guidance

Personal tools