Moving a Visual SourceSafe project to StarTeam
By: Jeremy North
Abstract: Details the steps required to import a current Visual SourceSafe project into StarTeam
Introduction
This article discusses the steps that it takes to move an existing Visual SourceSafe project to StarTeam. StarTeam Standard comes with the Enterprises and Architect editions of Borland Delphi 2005.
To begin the migration we need to know the location or the srcsafe.ini file and the password to access the Source Safe database. For the purpose of the article,
we are just going to add the project to the Test Database included when you install StarTeam.
The first thing you need to do is fire up the StarTeam client application. Unfortunately this cannot be done using the Delphi integrated client at present. Im not sure if this functionality will be added in the future. Figure 1 shows the StarTeam windows client started.
Figure 1
Preparing your Visual SourceSafe project for conversion
Before you start the conversion process you should be mindfull of the following items:
- Visual SourceSafe needs to be installed on the same computer that runs the StarTeam server
- If you wish to preserve the Visual SourceSafe history then each user that has checked in changes to your Visual SourceSafe project should be added as users to the StarTeam server. These users do not need to be licensed for the history to be imported correctly.
- Make sure all objects are pinned
- Make sure all shared files are pinned to the same version
- Make sure all Visual SourceSafe passwords are less than seven characters long. This is not as important if you are going to convert the StarTeam project to be a native StarTeam archive before allowing Users access.
Full details are discussed in the Help Topic Preparing to Wrap a VSS Project.
Creating a New Project in StarTeam
We need to access the New Project wizard and this is done by either selecting Project|New or clicking on the blank document icon on the Toolbar. The New Project wizard is displayed (Figure 2). This initial screen of this wizard lists all available StarTeam servers. You can also Add, Delete or modify properties of servers.
Clicking the Next button asks for the project name and also allows you to set a project description if you want. Both of these items can be changed after the project has been created.
You will also notice from the screenshot (Figure 3) that at the bottom of this dialog there is a button labelled Foreign Archives. This is where we tell the New Project wizard that we want to import from an existing archive.
 |
|
|
Figure 2 |
Figure 3 |
The StarTeam Standard edition allows you to import projects from either PVCS or Visual SourceSafe. If you want to import projects from another source code project, you need to contact Borland StarTeam support.
In this dialog (Figure 4) you need to check the Create project from checkbox. Once you checked the Create project from checkbox and you only have Visual SourceSafe installed, additional information is shown in the dialog (Figure 5). This allows you to set the location of the srcsafe.ini file and enter in your Administrator password to access the existing Visual SourceSafe archive.
 |
 |
|
Figure 4 |
Figure 5 |
Once OK is selected you then need to locate the project you want to migrate in your Visual SourceSafe project hierarchy. Click on the next button to continue. Figure 6 show how the Visual SourceSafe project hierarchy is loaded into the wizard.
Now you need to set the working folder for your project. If the existing Visual SourceSafe project had a working folder selected, then that is used as the working folder. You can change this folder if you wish.
Once you have entered in the working folder for the project, the New Project wizard is finished.
 |
|
|
Figure 6 |
Figure 7 |
Working in the StarTeam clients to complete the import process
Once you have completed the New Project Wizard you can now see your new project in StarTeam (Figure 8).
NOTE: Everything we do in the StarTeam windows client from now on is also possible in the Delphi integrated client. To complete this in the integrated client however does require some additional steps before proceeding. To complete the import process using the integrated client you must place the project you are importing into StarTeam. You can do this by following the steps outlined in the following article (
http://bdn.borland.com/article/0,1410,32959,00.html ).
The folder item in the left pane represents the current folder view. In the right top pane there is a list of all files that are visible to that view. The bottom right pane gives further information on whatever is currently selected in the top right pane.
If we focus on the top right pane for the moment, we can see two entries, both of which have a plus sign next to them. This is the default Filter for your view. You can create and save your own filters but for the purpose of this article, the default filter is fine.
What we do notice here is that the two items display a status. The first status is unknown and contains 12 items, while the second status is Not In View and contains 14 items. There are a number of possible statuses for files in a view for StarTeam. Neither of the status listed here are ones we really want to see.
Well address the Not In View status items first and come back to the Unknown status items shortly.
Figure 8
Expand the Not In View tree by selecting the plus button to reveal all files that have the Not In View status.
Figure 9
As you can see from Figure 9, there are a number of files listed with the Not In View status. A file with a Not In View status means that it doesnt exist in the StarTeam project. A lot of the time, files that are marked with the Not In View status you dont ever want to put into your StarTeam project. For files that you dont want to add to StarTeam, you can exclude them from being listed.
Excluding files from current view
To exclude files from the current folder view you need to access the properties for that folder. There are two ways to access properties
for a folder; by displaying the context menu for a folder and selecting Properties, or by using the Properties menu item in the Folder menu.
Figure 10 displays the Folder Properties dialog with the Exclude tab selected. Add your various matches to the Local exclude list edit. If you allow for inheriting excluded lists, those file specifications will
display in the Inherited exclude list edit. You cannot modify the Inherited exclude list items.
As the folder selected is the root folder there are no inherited exclusions.
For the purpose of the project listed in the screenshots, I have applied the following file specifications to be excluded (as displayed in Figure 11):
*.dcu;*.ident*;*.~*;*.local;*.dsk;*.scc
 |
 |
|
Figure 10 |
Figure 11 |
Once the exclude file specifications have been entered and you select OK there may still be some files left in the Not In View status from the import. It is possible that there will not, but in this instance I added a new dialog to the Bookmark Viewer
project that I never added into Visual SourceSafe. We shall return to these files shortly but first well look at the files that have a status of Unknown.
Figure 12
Dealing with the Unknown status
To fully understand what the Unknown status means, we can consult page 201 of the user guide.
| The file in the working folder has the same name as a file in the view but the file was not checked out from the project. You might have copied it from another location. Use Update Status to determine the correct status. |
So as the user guide says lets try and use the Update Status function. This is available from either the File menu
or the context menu in the file view. Select all files that have the Unknown status and select the Update Status menu item.
Figure 13 display the results from calling Update Status. You will notice that some of the selected files are now given the status of current, while others still have a status of Unknown.
Figure 13
The files that have been marked with the Current status occured because what is in StarTeam matches what is on disk. The files that are still displaying as Unknown is because they have been modified since the last check in from Visual SourceSafe was done. So to get these files into StarTeam
with a Current status we need to do a check in, but there is a catch
Figure 14
Forcing the Issue
As we have just done an import from Visual SourceSafe and these files have an Unknown status we cannot just perform a vanilla check in. We must do a Forced check in. To do a force check in, select all files that still have the Unknown status, from the File menu (or context menu) select the Check In menu item. The Check In dialog is displayed (Figure 15). Be sure to give the Check In a meaningful comment (like Im sure you always do) and as a forced check in is needed, select the Force check-in option.
You can also configure StarTeam to require a check in comment. This can be done by selecting the Properties menu item from the Project Menu. On the options tab you will see a checkbox labelled Require revision comment when files are checked in. Selecting this option will mean that no Check In will be possible unless a comment is entered in the Check In dialog.
Figure 15
After the force check in has been completed the status of the selected files should be now Current. We can now turn our attention to the files that have the Not In View status again.
Figure 16
From the filter combo box on the toolbar select the predefined file called Files Not In View. This filter allows you to only see the files that have the Not In View status. Since we just want to add the Not In View files to StarTeam, we just select the Add Files menu item from either the File menu or File view context menu.
Figure 17
Unlocking Files
StarTeam does not require a file to be locked for either Check In or Check Out. You can also lock files if you choose in the File list, but these locks can be overridden with a force check in if required. The following information is included for the instance where your StarTeam project does not use locks. Figure 18 shows the Add Files dialog with the Lock Status of Unlocked selected. Unlocked is the default Lock status. Select the OK button to add the selected files into StarTeam dont forget your meaningful comment!
Figure 18
Figure 19 now displays the file list using the Files In View filter. This filter displays all of the files that are in your StarTeam project. If you look at the Locked By column you can see that some of the files are locked and some are not. We dont want any of the files to be locked by a user. To remove the lock for the locked files, select all of the locked files and then select the Lock / Unlock (Ctrl+L) menu item from the File or context menu.
Figure 19
Make sure the Unlocked item is selected (it is by default) and click on the OK button. Now all files in your StarTeam project should be current and unlocked!
Figure 20
Figure 21
During the import the labels from the Visual SourceSafe are preserved and now visible in the new
StarTeam project. To access the Labels dialog select the Labels menu item for the project (View | Labels)
from the View menu. To view a label you need to create a new view. The New menu item on the View
menu is a good place to start for doing that.
Figure 22
Going Native
At this stage your StarTeam project still relies on your Visual SourceSafe DB being accessible.
You can verify this by selecting the Properties menu item from the Project menu. The properties dialog will indicate that the project type is Visual Sourcesafe.
For some, this won't be an issue but if you are going to be using StarTeam exclusively from now on, it is best to convert your wrapped VSS project in to a native repository.
Before converting your wrapped StarTeam project to use a native StarTeam repository, I recommend setting up your StarTeam server to support E-Mail.
Enabling E-Mail Support for the Server
Before converting the archive to be StarTeam native format I recommend setting up email support for your StarTeam server.
To setup E-Mail support:
From the StarTeam win32 client (this is not possible in the IDE Integration):
1. Tools | Server Administration
2. Select the General Tab if required
3. Locate the E-Mail groupbox on the General Tab and check the Enable e-mail support option.
Also enter in the SMTP server details that StarTeam will use to send the emails.
When the E-Mail is sent, it is sent to the User who initiated the conversion - some make sure that user has an email specified in their account properties.
To make your wrapped StarTeam project use a native StarTeam archive, select the Convert to native format... menu item on the Tools Menu.
When you select this option a warning message is displayed which basically says:
- Don't allow anyone access to the StarTeam or Visual SourceSafe projects while the conversion is taking place.
- Once the conversion is complete, the Visual SourceSafe project will no longer be updated.
Once the conversion is complete there will also be a log file generated in the StarTeam repository folder. The log file is prefixed with GoNative.
Example E-Mail message (if E-Mail support configured)
Subject: StarTeam Go Native Process
Body: StarTeam has successfully assimilated the foreign archives for project
%project_name%
NOTE: if your Visual SourceSafe database is large the conversion can take some time to complete. This is why I recommend setting up E-Mail support.
Didn't Go Native?
If you decided not to convert your StarTeam project to be a native StarTeam archive then I suggest viewing the two following help topics on what is and isn't possible with a non-native project.
- Understanding VSS to StarTeam Interoperability
- Understanding StarTeam to VSS Interoperability
Conclusion
So we have finally finished importing a project from Visual SourceSafe into StarTeam. Now you can explore the StarTeam integration in Delphi 2005 some more.
If you are interested in the Bookmark Viewer project that was shown in this article, you can download it (with full source) from Code Central from
http://cc.borland.com/ccweb.exe/listing?id=22326. It is also included in the examples download available for Delphi 2005.
Server Response from: BDN9A
|
|
