Source Controlling Projects and Solutions in Team Concert for Visual Studio

Build basis: Rational Team Concert for Visual Studio 1.0.1.1 (Beta 1)

Summary

This article explains how to structure and source control new solutions and projects in a way which works well for team development in Team Concert. In addition, for existing solutions and projects which are controlled in another tool, we will outline how to migrate them into Team Concert.

Note: Part of the information presented here may apply to this version only, and is subject to change in future versions.

---

1 Concepts

The article assumes you have installed the Rational Team Concert for Visual Studio, have a connection to the Jazz server, and have created a repository workspace. If this all sounds foreign to you, please start by reading the getting started tutorials for setting up a project and team, then the basic Source Control tutorial for the basic concepts. These tutorials show the steps within the Eclipse based client but all the steps are similar in the Visual Studio client.

1.1 Activating Jazz Source Control

The first step is to set Jazz Source Control as Visual Studio's current provider from the Source Control options page in the Tools > Options... main menu. If you didn't see the Share Project(s) in Jazz menu in solution explorer, you'll start seeing it now.

1.2 Local File Area

The local file area is a location on your file system that contains a local copy of your repository workspace files. It is analogous to a ClearCase view, or Visual Source Safe's working folder. When you share a solution with Team Concert, the parent folder of the solution folder will automatically get converted to a file area. What this also means is that if you are already in a file area, you can only share the top level folders under it.

You can explicitly designate any folder on your file system as a file area by loading repository workspace(s) into it.

In Figure 2, C:\Jazz\Local Copy Areas\Beta Development will become your file area and the Team Concert source control provider will automatically track changes made within this file area. It is recommended that you always work off a file area. That way, you are shielded from making accidental references between solutions/projects that belong to different file areas. Ensure that all projects that belong to a solution, are all in the same file area.

1.3 Adding a solution and projects to Source Control

In order to store a solution that's on your file system into a Jazz repository, you'll need to share it using the Share Project(s) in Jazz from solution explorer's context menu.

Sharing a solution exhibits the following behavior

• If not already in a file area, converts the parent folder to a file area, and shares in Jazz.
• If already shared (by virtue of it being a nested directory, or have been shared in Jazz from a different client, it will simply write source control bindings to the solution or projects.
• If previously shared, but later disconnected, re-shares in Jazz. Re-sharing will reconcile the local and remote copies and check-in only what has changed.

Sharing a project exhibits the following behavior

• Disabled as long as the solution which its contained in is not shared.
• If the project's files reside physically under the solution folder, source control bindings are written into the project to enable Jazz Source Control operations.
• If you do not see the source control glyphs in the Solution Explorer on the new project, or do not see the new changes in the Pending Changes window, refresh from there.

Implicit Share - when can this happen?

• You have already shared the solution folder from the Eclipse Team Concert client, but need to work with it in Visual Studio, source control bindings need to be written.
• The folder you are trying to share is a nested folder under an already shared folder.
• A project folder under an already shared solution folder.

If the solution folder you want to share, is not directly under the file area there might be two cases, one, the top level folder that contains this solution folder is already shared, in which case, the new solution folder is implicitly shared, and sharing the solution from Visual Studio, will only add source control bindings into it. In the other case, you'll be asked this question:

Choose Yes, if you intend to share the top level folder, you can always add ignore rules to any file/folder that you don't wish to share from the wizard that follows. If you intend to restructure your solution to avoid this warning, choose No.

Note: Changes to files that are not part of the Visual Studio solution system will not be automatically tracked by Jazz, you'll need to track them by explicitly refreshing Pending Changes when needed.

1.4 Disconnect

You can disconnect a shared solution from Jazz using Disconnect Project(s) from Jazz menu in solution explorer. For a solution, this option not only disconnects the solution folder from Jazz, but also removes Jazz source control bindings from both the solution and projects. Pending Changes stops tracking changes to the solution from then on. Removing bindings is particularly useful, when you want to make a copy of the code for another user who might not have Rational Team Concert client for Visual Studio installed. Otherwise, they'll have to deal with this message:

Disconnecting individual projects, will merely remove source control bindings from the respective .proj files. Again, like Share, if you try to disconnect a nested solution folder, you'll be asked this question:

2 Migrating from another Source Control provider

In this section, we'll try to migrate a solution structure that was part of a different source control provider in Visual Studio to Jazz Source Control. It does not cover migration of the source control artifacts which maintains file history but instead focuses on migration of source control bindings from a different provider. You must migrate the source control bindings to Jazz Source Control to perform source control operations in the Visual Studio environment. This example shows a solution with existing bindings to the ClearCase source control provider.

1. Create and load a repository workspace into a file area.
2. Copy the solution structure from the previous provider into the root file area folder into which the repository workspace was loaded.
3. Remove read-only attributes for the entire folder structure - most source control systems will have it set.
4. Remove the current source control bindings from the solution and projects. Do this by hand by opening the solution (.sln) and project (.proj) files and removing the files in bold below:

Example Solution file

Microsoft Visual Studio Solution File, Format Version 9.00
# Visual Studio 2005
Project...
EndProject
Global
 GlobalSection(RationalClearCase) = preSolution
 SourceControlProvider = RationalClearCase
 EndGlobalSection
...
EndGlobal

Example project files

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 <PropertyGroup>
  ...
  <SccProjectName>Rational ClearCase</SccProjectName>
  <SccLocalPath>Rational ClearCase</SccLocalPath>
  <SccAuxPath>Rational ClearCase</SccAuxPath>
  <SccProvider>Rational ClearCase</SccProvider>
 </PropertyGroup>
...

5. When combined with an upgrade scenario, say, the projects you are trying to migrate were originally created in a Visual Studio version below 2005, and your current source control provider is not available in the version of Visual Studio you are using Jazz with, the upgrade itself won't proceed unless you performed step 4, with errors such as these:

Figure 6: Error when bindings aren't removed

6. Once the bindings from the previous source control provider have been removed, open the solution again and share it.

7. During share, add rules to ignore files left over from the previous source control provider, though not a mandatory step. Some examples with ClearCase are *.db, *.ccscc, *.vspscc, *.vsscc, *.vssscc, etc. Or simply remove them from the file system.

3. Best Practices for the Solution Physical Structure

To ensure that the development and build processes work effectively in a team environment, it's essential to start with a correct solution folder structure that is consistent across all the development workstations and build servers.

Failure to create a well designed solution folder structure will result in problems in the later addition to a source control provider repository and the recreation on other machines.

Team Concert follows and recommends the best practices as outlined by Microsoft team development literature, for example in the article about structuring solutions for Visual Source Safe.

3.1 Hierarchical Folder Structure

Visual Studio allows many different physical organizations of solutions and projects. Unfortunately not all of them make it easy to share them in a team. The best way to organize a solution in a team environment is to use a hierarchical folder structure, where the solution is the root and the projects are sub-nodes. This keeps the solution and the projects in the same file area, or physical area on disk. The solution is created in a root folder of the file area and the individual projects are created in subfolders below the root folder. The solution folder contains the solution file, and individual project folders are under the solution folder.

To ensure minimal number of steps for sharing a solution in Jazz, and consistency with references between solution and projects, and among projects, here's what is recommended. If your solution is organized as shown in Figure 7.

The structure on disk will be that as shown in Figure 8. The directory called Beta Development is the root of the file area.

If you have existing solution structures that do not conform to this guideline, there are ways to share it in Jazz too, albeit a few extra steps. We'll discuss it with an example in the following topic.

3.2 Partitioned single solution model

In this model, a set of projects are grouped in separate sub-solution files, and there is one master solution file that includes projects from all the sub-systems. This results in projects being contained within more than one solution file. Figure 9 shows one of the solutions and the projects in the Solution Explorer.

In this example, ClassLibrary1 belongs to Solution1, that we shared already in the previous step, ClassLibrary2 belongs to Solution2, which is yet to be shared, and ConsoleApplication1 exists in the MasterSolution folder. Each of the solution directories are peers in the file system as shown in Figure 10.

It is recommended that you share projects from their parent solution, before working with them from the MasterSolution. So, as per this, open Solution2 and share it. Now, open the MasterSolution. You'll see both ClassLibrary1 and ClassLibrary2 as shared, and the only remaining task is to share the MasterSolution itself.

Let's say, we didn't follow this recommendation, and tried sharing the MasterSolution first, you'll be asked this question:

Answering "No" will not add bindings to ClassLibrary2 (that belongs to Solution2) and you'll have to share this project from it's physical parent solution first before you can access any of its Jazz Source Control operations.

After sharing, if you were to attempt sharing ClassLibrary2 again from MasterSolution, you'll again get a similar message:

Now, share Solution2, which is the parent of ClassLibrary2, and come back and open MasterSolution to see all projects under it shared. After these steps, you should be able to work out of any of the solutions in conjunction with Jazz Source Control.

4. Other tips and tricks

4.1 Files and Folders outside of Visual Studio

You might have outer-system assemblies that are not built as part of your system build process (such as third-party controls and libraries) in a separate folder, outside of any solution, that you want to share in Jazz. You can do this, by creating a solution at that location (say, 3rd Party\3rd Party.sln), and sharing this solution. You have two choices here, while sharing, you can add an ignore rule for the solution file itself (3rd Party.sln), since the solution is not useful beyond share, and you have other regular solutions in the same local copy area using which you can track the pending changes in the 3rd Party folder too, or you can use the solution to track pending changes to the containing folder.

Note: Since none of the files/folders in the 3rd Party folder are part of the solution, you'll need to refresh the pending changes view explicitly, to track file system changes to them.

4.2 Ignoring files/folders in Jazz

While sharing, you'll need to create Ignore rules for files/folders that don't have to be source controlled. There are certain default ignore rules that are applied, that include *.suo, *.user, *.ncb, *.aps, but there are others like the bin and obj folder you may want to ignore. As an example, the second page in your Share wizard could look like this:

Figure 13: Ignore paged of the Share wizard

If you forgot to do it here, you can always use the Add to Ignore List option from the Solution Explorer. This is particularly useful, when sharing a new project from an already shared solution. Try it, and you'll be told:

Since, you didn't get a chance to review ignores at this stage, do it from the solution explorer:

4.3 Don't forget to save solutions and projects

One scenario where developers are bound to make mistakes is when making changes to projects or solutions by way of add/delete/rename/move files. You must save the project and solution after these changes, otherwise, a subsequent undo/suspend/discard of the file change can leave the project/solution confused.

Let me demonstrate this with Rename as an example:

1. Let's say you renamed a file belonging to a shared solution

Figure 16: Renaming a file

2. Pending changes will refresh to reflect this change, don't save the project yet.

Figure 17: Rename pending changes

3. Undo the rename

Figure 18: Undo the rename

4. Previous step will leave the project confused. The project has recorded the rename, but not the undo, because it happened outside its knowledge

Figure 19: Project after undo

5. At this point you have to be careful not to save the project (e.g., unload without saving, and reload), so that you are in a state you started with (before the rename)

6. A better practice would be to Save the project after the rename, so both changes go hand in hand. When you have to undo, you undo both changes together.

Figure 20: Undo both rename and project