TFS Integration Tools – How do I use the Clear Case Selected History Adapter?
Another great question and a great trail of evidence gathered by Bill Barnett that deserves a blog post :)
… selected history migrations …
It is assumed that you have installed the TFS Integration Tools on your system. If not, alternative links are included.
- Understand and prepare the environment
- In the product file “Documentation\Readiness Package\Guidance\TFS_Integration_Platform-ClearCase_Base_Migration.mht” look under the heading “Selected History Migration”. Particularly look at the steps under “Preparation”.
Alternatively find the TFS Integration Platform ClearCase Base Migration document here.
- In the product file “Documentation\Readiness Package\Guidance\TFS_Integration_Platform-ClearCase_Base_Migration.mht” look under the heading “Selected History Migration”. Particularly look at the steps under “Preparation”.
- Configure the session
- In the product file “Documentation\Readiness Package\Guidance\TFS_Integration_Platform-Configuration.mht” under the heading “Semaphore File Analysis Addin”, there is an accurate description of how to use the Semphore File Analysis Addin and what should go into the file.
Alternatively find the TFS Integration Platform Configuration document here. - “Documentation\Readiness Package\Scenarios\CC and TFS Synchronization\CC_TFS_CC_to_IN.XML” is an example configuration file from a POC that used the Selected History Adapter. The way that the Semaphore File Addin is configured there is different than the recommended configuration document mentioned above above, but still works because we supported it for compatibility.
Alternatively find the example config files in this ZIP file.
- In the product file “Documentation\Readiness Package\Guidance\TFS_Integration_Platform-Configuration.mht” under the heading “Semaphore File Analysis Addin”, there is an accurate description of how to use the Semphore File Analysis Addin and what should go into the file.
What are the basic steps in a nutshell?
- Peruse the migration guidance documentation and understand the constraints.
- Create a migration session configuration using the TFS Integration Tools admin shell.
- Edit the configuration file XML in the admin shell.
- Update the configuration as per point 2 above.
- Save the configuration to the database.
- Run the migration session.
Bill E. has just shared an interesting view, which must be included “as is” … it is a real nugget:
Selected history basically means that the user gets to drop a series of trees on disk and touch a semaphore file after each update is complete to cause the adapter to synthesize history in TFS. If a file on disk has changed the adapter will pend an edit and if there are no changes the file will not be touched in TFS. If the selected history adapter had no idea how to talk to CC at all you would get the behavior we get with the normal File System adapter when a file is renamed – it would show up as a delete/add. The CC selected history adapters know enough to interrogate CC to try to preserve rename history. The semaphore file can be used both as a trigger to cause the changes to move and as a way to control the checkin comment for a set of changes. A typical automation solution built around the selected history adapter might use a build report or custom tooling to create a comment that represents the set of changes in a particular build|release and use the act of writing that comment into the semaphore file as the trigger for the update in TFS.
At a very high level, the selected history adapter has far less exposure to the CC APIs and it interacts with CC far fewer times. If a team makes 100 changes in a day and a selected history migration is configured to pick up the nightly build you have 99 fewer chances a day for something to go wrong. If a customer uses it to select “interesting” historical snapshots, like releases or weekly builds, they get lossy history compression that can speed up an import considerably. Ask people whether they really need 10 years of details and 10 TBs of information in TFS to get started or if it is enough to have trees that represent all of their releases. They can compare source between the trees that they imported, so seeing that a particular file changed between V1 and V2 is still possible, but audit type features are left for research in CC. In environments where there are no legal or regulatory issues driving audit-style queries, the history growing in TFS moving forward tends to reduce the need to consult CC for details over time.
Also, the complexity is often reduced because there is often tooling available in an environment to get a whole tree from CC. That might be a nightly build process running on source in CC or some tooling to generate config specs that can be used to get trees for historical releases. The selected history adapter can be a much more robust choice to build a solution around when the user can tolerate history compression.