Flexible mapping of sources to Jazz components
The Rational Team Concert client for Microsoft® Visual Studio IDE originally supported the Microsoft recommended structuring of projects and solutions for share scenarios. However, we soon received a lot of user feedback on the need for a more flexible approach towards Share. Users wanted to be able to share projects or folders as well as solutions. So, since 3.0, we’ve made share flexible. While doing so however, we’ve ensured we didn’t change what you were used to.
In this article, we discuss the new and improved share scenarios that the RTC Client supports for Visual Studio users. We start by describing some concepts that are necessary to understand Share and follow it up with new ways of mapping your sources and sharing into Jazz.
Concepts
Sandbox
Sandbox is a location on your file system where repository workspaces/components are mapped. It is analogous to a ClearCase view, or Visual Source Safe’s working folder. You can designate any folder on your file system as a sandbox by sharing content from within, loading repository workspace(s), or pointing to a sandbox from the Sandbox History node in the Team Artifacts view. The Pending changes view will always track your current sandbox while logged in.
Share Root
Share Root is the root of the shared portion of the file system under the sandbox. When you share a solution/project, you are actually sharing the containing top level folder under the sandbox, which then becomes the share root. So, if your sandbox is C:\Jazz\sandbox1 and your solution is C:\Jazz\sandbox1\Root\Solution1\Solution1.sln, then C:\Jazz\sandbox1\Root\Solution1\Solution1.sln will be the share root. You can share multiple root folders against every Jazz component in your repository workspace.
Bindings
In Visual Studio, several Source Control providers may be concurrently registered. A solution/project that is under source control is marked as being associated with a particular provider (in our case, Jazz) by way of bindings. When a solution/project under source control is opened, Visual Studio lets the designated source control provider take over.
Here is a sample of Jazz project bindings:
<SccProjectName><Project Location In Database></SccProjectName>
<SccLocalPath><Local Binding Root of Project></SccLocalPath>
<SccAuxPath><Source Control Database></SccAuxPath>
<SccProvider>Jazz Source Control Provider:{AC8810C5-F6E7-4145-83AA-FDFFF6F5506D}</SccProvider>
What Hasn’t Changed
Our recommendation about laying out solutions and projects on disk doesn’t change. Also the fact that Visual Studio requires us to add bindings into shared solution/projects will remain. We have changed a few things around Share, but we did not want to change what users were used to.
You can read about the recommended approach at Source Controlling Projects and Solutions in Team Concert for Visual Studio
What Has Changed
Our initial approach was to have one solution per share root. The RTC Client would let users share a solution against a Jazz component. One or more Visual Studio solutions could be mapped to a Jazz component. If a project folder was under a solution folder, the project could only be shared to the same component as the solution. If a project folder belonged to a solution hierarchy but physically resided under a different solution folder, the project and the solution whose hierarchy it was included in, could be shared against different components. Sharing therefore, was essentially solution centric.
From customer usage, we realized that this wasn’t always going to work. Some developers used the solution more like a placeholder for projects. They didn’t want to share the solution into Jazz at all. To share projects directly, users would create solution directly under the sandbox, so that the projects get created as share roots.
However, since we didn’t support sharing projects or folders against Jazz components anyway, doing this wouldn’t work as expected. We suggested a workaround — users would be required to create a solution around projects they wanted to share, and then they would share the solution folder, but add the .sln file to the ignore list. We realized however that the workaround was just a workaround, and the only real solution to this problem was for the RTC Client to support sharing projects. This meant that we would stop treating the solution and project differently.
Sharing projects
You can now share projects without having to share the solution. This gives you the flexibility to create personal solutions and not check them in at all, while still sharing your projects with other developers. You can see in the figure below that the projects are shared, but the solution isn’t. The Sandbox Explorer shows how the sources may be laid out on disk. If a second user loads and opens such a project, Visual Studio will create a temporary solution, but the user has an option to just work with the project without having to even save such a solution.
Typically, users who work with projects as opposed to solutions have the Always show solution unchecked, like in the figure below. They just open projects and work with them directly. Because there wasn’t an option until 3.0 to share projects until the solution was shared, such users would have a hard time figuring out how to start with Share in Jazz. With share now being enabled for both projects and solutions in the same way, this isn’t a problem any more.
Sandbox selection
When not in a sandbox, our earlier approach was to assume the parent directory of the solution folder to be the sandbox. If you are sharing projects alone, and not the solution, we won’t know what to “assume”. We ask you instead to select a sandbox.
Choosing a drive for a sandbox
It might be that you have come from a ClearCase background where using a mapped drive is the norm, and you’d like the same here. The Visual Studio client didn’t work well with directory roots for a sandbox as explained in the article, Workaround: Known issue with tracking changes in a sandbox loaded directly under the drive . That’s changed now, and you can have a mapped drive as your sandbox.
Solution directly under sandbox
If your project folders are directly under the sandbox, that is they are share roots themselves, then your solution file might be directly under the sandbox. In such a case, you can share just the projects without needing to share the placeholder solution.
Solution outside the sandbox
When you create Website projects, for instance, Visual Studio creates the solution files in the Projects location specified under Tools->Options, even though you choose a location within the sandbox for the Website.
Pre-3.0.1, we recommended that users create a blank solution within the sandbox first, and then add a Website project to this solution, instead of letting Visual Studio create the solution in the default configured location. Though this is also the Microsoft recommendation, some users told us they didn’t want to share solutions at all, so they didn’t care where they got created. So, we now support sharing such projects too. Just make sure that the location where the solution resides is not a sandbox. We don’t yet support working with multiple sandboxes in a single Visual Studio instance.
Adding projects to a shared solution
When you add a project to an already shared solution, though the project might be implicitly shared due to the fact that its under a share root, Pending changes will not track the project (unless you share the project to add bindings). You now have an option to automatically share such projects.
Multiple projects
When a solution is chosen to be shared, there could be projects which are not under the solution’s share root. Previously, we presented a warning to the user to confirm whether they wanted to leave out those projects or just add bindings into them. Customers found these messages very confusing. We now allow users to additionally share these roots too. For projects that were already shared, we allowed users to review ignores and add bindings. Now, if our share list includes some projects that are already shared and some that need to be, the share wizard will indicate that. For example, in the figure below, the Documents folder is a share root, we only need to add bindings to the Example1 project, whereas Solution1 and all projects under it are unshared. The share root expands to show projects to which source control bindings will be added, with an option to select/unselect additional share roots.
Reviewing Ignores
When sharing a solution/project that is already under a share root (you might have shared from Eclipse/Sandbox Explorer in Visual Studio), the share wizard will start with the Review Ignored Resources page. After a successful share, you’ll see unresolved changes related to .jazzignores and source control bindings added to the solution and project files.
Creating workspaces
Pre-3.0, if you chose to create a new workspace during share, you didn’t really have much of a choice. It created a workspace and a component with the same name just to back up your work. You can now choose a flow target as well as create and share to a new component as part of the share wizard itself.
Sharing anywhere within the component
Pre-6.0.1, when sharing a project or folder, you could only choose a component in your repository workspace, which means that you could share it only as a top level folder within the component. The share wizard now allows you to expand the component to choose a folder or create new folders under which you want to share. With this, it is possible to share projects or folders anywhere within the component.
Sandbox Explorer
You no longer have to create a wrapper solution to share content that is outside of Visual Studio’s solution structure. It’s the same for linked sources outside your project. Open the Sandbox Explorer tool window either by choosing to Explore the current sandbox from Sandbox History, or from Team Concert->Windows->Sandbox Explore main menu. The Sandbox Explorer has a rich set of source control menu options,, that lets you work with files and folders outside of a solution hierarchy. For more information on using the Sandbox Explorer, please read Working with the Sandbox Explorer in the Rational Team Concert Client for Visual Studio.
Sharing files from Sandbox Explorer
Beginning 6.0.4, you can share files directly under the sandbox or from within unshared folders in your sandbox from the Sandbox Explorer.
Disconnect
Disconnecting solutions/projects now gives you an option to additionally disconnect the share roots, choosing No will remove the source control bindings only.
Conclusion
In RTC 2.x and before, users could share solutions/projects in Jazz Source Control repository from the Visual Studio client, but there was not a lot of flexibility in how sources could be mapped to Jazz components. RTC 3.0 onward, sharing has become much more flexible, with the capability to share just the projects (with the solution as a placeholder), or share folders, or have multiple share roots. All of this being quite transparent to the user. With these changes (of treating both solution and project and even top level folders similarly), things have become simpler. Also, the source control bindings stored by Visual Studio are more in sync with the share status. The 6.0.x releases have further enhanced the flexibility around sharing, considering both parity with the Eclipse client, as well as usage scenarios specific to Visual Studio.
For more information
- Source Controlling Projects and Solutions in Team Concert for Visual Studio
- Tracking changes in a sandbox loaded directly under the drive
- jazz.net Work Items 95742, 100516, 110572, 129421, 363100 and 383423
About the author
Priyadarshini Gorur is the technical lead on the Rational Team Concert .NET clients team. She can be contacted at priya_gorur@in.ibm.com.
� Copyright 2017 IBM Corporation