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.
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.
The first step is to set Jazz
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.
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.
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.
the solution folder you want to share, is not directly under the file
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.
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:
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.
Example Solution fileMicrosoft Visual Studio Solution File, Format Version 9.00
# Visual Studio 2005
GlobalSection(RationalClearCase) = preSolution
SourceControlProvider = RationalClearCase
Example project files<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
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
Once the bindings from the previous source control provider have been removed, open the solution again and share it.
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.
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.
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
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.
In this model, a set of projects are grouped in
separate sub-solution files, and there is one master solution
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
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
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.
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.
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:
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