How does VSS Converter works?

VSS provides IVSS automation interface to program. This interface is used to retrieve the information from VSS repository. Converter reads the history from VSS repository and adds into an intermediate database (SQL). This history is processed to take care of ambiguities arising due to rename/share and to remove residual information about destroyed items. After the database is processed, it adds the actions (that happened in VSS repository) in chronological order in Team Foundation.

Why chronological order and why intermediate database?

We could have choosen to migrate history per item i.e. for the directory tree we migrate all actions done on perent then similar way migrate all its children (a breadth first approach). But this way we could not have preserved rename and move action history. To preserve this history we had to go in chronological order.

 In VSS an item's (a file or folder) history is stored in such a way that certain actions go into item's history records and certain actions go into it's parent's (folder containing this item) history. Actions that go into item's history are: Create, Edit(only for files), Branch, Archive and Label. Actions that go into parent's history are: Add (this is same as create), Move, Rename, Share, Delete, Destroy. All the actions that go into parent's history are stored with name of item at the time this action happened. actions in item's history are stored with item's latest name. So if we did following actions in VSS:

D1: Add $/A

D2: Add $/A/a.txt

D3: Edit $/A/a.txt

D4: Rename a.txt to b.txt

D5: Edit $/A/b.txt

D6: Label $/A 'test'

D7: Rename A to B

(D1 to D7 refer to Timestamp in increasing order)

Then we have following history listing for each

$/:

1. Created

2. Add A

3. Rename A to B

$/B

1. Created

2. Add a.txt

3. Rename a.txt to b.txt

4. Label 'test'

$/B/b.txt

1. Created

2. Edited

3. Edited

With this kind of history we need to combine all the data and get proper names at each point in time for every item. this was our primary need for using an intermediate Database. So we decided to put all the history in SQL, sort it chronologically and figure out right name for each item at any point in time.

Processing Database

The history we read from VSS needs to be processed to be suitable to be put into Team Foundation. We take one pass through all the actions in the history in reverse chronological order to process the database. Following are the Cases that needs to be taken care of:-

 

Destroyed Items: We do not have the history for destroyed items. But the actions like rename, share, delete, undelete, etc go into parent history are still there. We have to remove such actions from our database so that we have a proper history without any history of destroyed items. For this we also write all the add actions to intermediate database (add action goes into parent history and create action goes into history of item being created we presently ignore add actions). Then all the history for destroyed items is removed from database in between the time window of their creation (marked by add action or share action) and destroy action.

Rename of Items: We do not get proper full path names at the given versions for VSS items. But these names are needed when we are putting things in Team Foundation. To figure out the proper names we start we latest name and apply all renames in reverse chronological order.

Move of Folders: Move is also like rename (due to move parent name changes) we do not get proper full path names at the given versions for VSS items. But these names are needed when we are putting things in Team Foundation. To figure out the proper names we start we latest name and apply all moves in reverse chronological order.

Share of Items: We get history of shared items from both source location (item shared) and destination location (item shared to) this is not correct as we are migrating share as a copy action so at the destination location all the history before share needs to be deleted.

Adding To Team Foundation

To add to Team Foundation we create a workspace on local machine for the converter tool. Then we read actions from intermediate database in chronological order. Then repeat that action on Team Foundation(most of the action in VSS have corresponding action in Team Foundation all the special cases are mentioned seperately). To do actions in Team Foundation we use web service exposed by Team Foundation.

 

Clubbing of Actions

In Team Foundation there is a concept of changesets. More often than not, a task-specific checkin involves multiple, interdependent revisions to two or more files. Consequently, changes to a single file don’t usually make sense unless they are accompanied by thorough checkin notes.

A changeset is a logical container into which VSTF bundles everything related to a single checkin operation. A changeset consists of:

• source file and folder revisions (adds, renames, edits, deletes, moves)
• related work items (bugs, etc)
• system metadata (owner, date/time, etc)
• checkin notes and comments

In VSS every file change goes as different version. We map these seperate changes into changesets by clubbing them on basis of checkin comments. Hence consecutive changes made by a single developer having same checkin comment are taken as related to single checkin and migrated to Team Foundation as single changeset. The idea behind this is that if we have same comment for all these changes these were related to same task and when user looks into the history he will get the information about what else was changed for this task.

 

This also helps us keeping number of changesets low. This ensures we do not degrade already stressed Team Foundation performance too much. A converter run generates enormous stress for VSTS server as we have multiple threads constantly bombarding server with requests for a long period of time. And above that if we have too many changesets each request takes much longer.

Special Cases

Share of file -

In VSS, you can share a file across multiple folders. Changes in one shared files is visible across folders where it is shared. Internally VSS creates soft links between shared files. There is not concept of sharing of a folder. When your share folder in effect a folder is created and all underlying files are shared. Team Foundation does not have equivalent of sharing. Shared files will be migrated by copying the version of the file, at the time of sharing began, to the destination folder. From then onwards, the changes made to the shared file are replicated to both copies.

Branch of file -

Though Team Foundation supports branching, converter does not migrate branch as sharing. Sharing is a pre-condition of branching. The migration of a shared file will result in copying the file to the destination folder. Migration of branch event will mean the changes made to shared file not being replicated to both copies any more. Hence, the changes to any branch will be migrated to the respective copy in Visual Studio. This section gives you a list of files that are either shared or branched in VSS. Converter will migrate these files as described in above.

 

Pin/Unpin – We do not migrate Pin or Unpin event as Pin is not supported in Team Foundation. Only currently Pinned items are labeled as Pinned.

 

Label –

• In Team Foundation there can be only one owner of a label so we do not migrate the user information for labels (include pin events).Also Team Foundation does not allow specifying dates for label on every item so it is not migrated. 
• In VSS any label on an ancestor is visible on the descendent as an implicit label. No such implicit label is migrated. A label is migrated only if the item was explicitly labeled.

Timezone issue inVSS -

VSS has a time zone issue that it stores client time as the time of action. So if two clients are out of sync or if they are in two different time zones then the history will have a lower version having later time of action. This affects the VSS to Team Foundation converter as it relies on the time of action to figure out the order in which action were done in VSS. Following are the scenarios where converter will fail to migrate the history properly.

 

Action	Limitation	Example
Edit	None
Add	Add of child may occur before create of parent. This may cause converter to give an extra error saying parent already exists. There is no data loss though.	History for $/A:   Ver 1: D2: created Ver2: D1: Added B   So when B is created A will automatically be created in Team Foundation and when converter tries to migrate the create action for A it will crib saying A already exists.
Label	Implicit labels may not always be same as in VSS.	Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D4. 4. Label $/A as test with time stamp D3.   After migration to Team Foundation the label test will come before create action for $/A/B/a.c.
Delete	If delete comes before any action that goes into child history(or any actions on descendents) then those actions will be lost.	Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D4. 4. Edit $/A/B/a.c with time stamp D5. 5. Delete $/A with time stamp D3.   The action create and edit for $/A/B/a.c will be lost while migrating to Team Foundation.
Undelete	The limitation is similar to that of delete only in this case if due to time zone issue the Undelete action comes after some actions on child or its descendents.	Scenario1: Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D3. 4. Delete $/A with time stamp D4. 5. Undelete $/A with time stamp D6. 6. Edit $/A/B/a.c with time stamp D5.   The action edit for $/A/B/a.c will be lost while migrating to Team Foundation.     Scenario 2: Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D3. 4. Delete $/A with time stamp D4. 5. Undelete $/A with time stamp D6. 6. Create $/A/B/b.c with time stamp D5.   The action Create for $/A/B/b.c will create the full directory structure $/A/B and whe the converter tries to do an Undelete it will crib saying $/A already exists and the undelete action will be lost while migrating to Team Foundation.
Rename	If rename comes before any action that goes into child history(or any actions on descendents) then those actions will go with the wrong name. No versions are lost but the full path for some versions may not be correct	Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D4. 4. Rename $/A/ to $/C with time stamp D3.   After migration to Team Foundation the rename will come before create action for $/A/B/a.c and a.c will be created as $/C/B/a.c.
Share	This is migrated as Add and has the same limitations as Add action.
Move	If move comes before any action that goes into child history(or any actions on descendents) then those actions will go with the wrong name. No versions are lost but the full path for some versions may not be correct	Consider the following actions in VSS.   1. Create $/A with time stamp D1 2. Create $/A/B with time stamp D2. 3. Create $/A/B/a.c with time stamp D4. 4. Move $/A/B to $/C with time stamp D3.   After migration to Team Foundation the Move will come before create action for $/A/B/a.c and a.c will be created as $/C/B/a.c.

Comments

• Anonymous
  May 04, 2006
  General
  If you only had time to read only one VSTS site, I suggest Rob Caron's: http://blogs.msdn.com/robcaron/...