Easing into Jazz Source Control

In this article, we are going to present a way of using the Jazz Source Control (SCM) Eclipse integration in a way that is familiar to Eclipse users who have used the Eclipse integration of other SCM systems such as CVS or SVN. We will start off by presenting workflows that can be controlled from an Eclipse resource view like the Project Explorer or the Package Explorer. We will then discuss what makes Jazz SCM different then systems like CVS and SVN and describe how to make user of the of Jazz SCM through the Pending Changes view.

Table of Contents


Eclipse users who are familiar with the Eclipse integration for repository tools, such as CVS and SVN, often have a hard time understanding how to use the Jazz SCM tooling in Eclipse. This is due, in a large part, to how Jazz SCM differs fundamentally from traditional repository tools. In this article, we present a way of working with Jazz SCM within the Eclipse based client that is similar to the workflow used for other Eclipse based repository tools such as CVS and SVN. However, the workflows we present are not the ideal workflow for Jazz SCM so we will also discuss what makes Jazz SCM different than these other repository tools and then present the workflow that we feel better makes use of the Jazz SCM capabilities.


The examples presented in this article assume that the following setup has already been performed.
  1. An RTC server is installed and configured.
  2. A user has been created and assigned a Developer license.
  3. A project area has been created using the Simple Team Process and our user has been added as a member of that team and been assigned the Team Member role.
  4. The user has installed the Eclipse client.

If you need to perform any of the above steps, a good starting point is Getting Started with Rational Team Concert: A Deployment Guide.

Saving Work using SCM

In this section, we are going to show some basic workflows for sharing work with a team. These workflows will involve working from a resource view such as the Packages Explorer of the Java Development Tools (JDT). What we will show is:
  • Sharing a new project in a stream
  • Making changes to the content of a stream

Sharing a Project to a Stream

To start off, we need to have something to share. Emily is our example user and she has created a project for a simple web server. In this section we’re going to show how she can make this project available to her team mates through her team’s stream.

When using the RTC Eclipse client, the first thing you need to do when you want to share new work is to launch the client and create a new Jazz Repository Connection from the Team Artifacts view by clicking on the Create a Repository Connection link. After you have added the connection, you will want to choose Manage Connected Project Areas from the context menu of the location in order to connect to your project area. Once you have done this, the Team Artifacts will look something like this:

Team Artifacts view

Now lets assume that Emily has a project in her client workspace that she would like to upload to the RTC server. Uploading a project for the first time is done using the Team/Share menu action.

Team Share Action

After choosing Jazz Source Control as the provider on the first page of the wizard, Emily then needs to enter a remote workspace name. We’ll talk more about the remote workspace later in the article.

Enter Workspace Name

Once the workspace name is entered, Emily can click Next and indicate that she wants the changes to end up in the stream and component of her team.

Pick Target Component

After clicking Finish, the changes will be in Emily’s remote workspace but they will not be in the stream. This is indicated by the outgoing change indicators in the Packages Explorer.

Outgoing Changes

To put the changes in the stream to make them available to other team members, Emily needs to deliver the changes to the stream. This can be done using the Team/Deliver action available from the context menu of the project.

Team Deliver Action

Emily can inspect the changes she is delivering and can make them available to her team mates through the stream by clicking OK.

Deliver Dialog

Once the project is delivered to the stream, the members of Emily’s team can now load and work on the project as well. However, before we show how to do that, we will show how Emily can make some further changes.

Making Changes in a Stream

Now that Emily has shared the project, she wants to make a few changes. She has edited the class TheServlet and saved it. As we see in the following screenshot, the class and its containing package, source folder and project are decorated with a yellowish background indicating that there are changes locally that have not been uploaded to the server.

Unresolved Change

Emily can make those changes available to her co-workers in their stream using the Team/Checkin and Deliver action which is available from the context menu of the changed file or any of its containing folders. This action will open the following dialog that allows Emily to associate a comment with the changes being delivered.

Checkin and Deliver page 1

One of the powerful features of Jazz SCM is the ability to link changes made in SCM to a related work item. By clicking Next, Emily is presented with a wizard page that allows her to associate a work item with the changes she is delivering.

Checkin and Deliver page 2

By associating a work item with her change, not only will Emily see that link in the history of the stream but the link will also be present in the work item itself. This means that anyone who views the work item can easily navigate to the changes that were made as part of that work.

Work Item with Link

Working in a Team

In this section, we are going to look at how to work with other team members using the actions available from a resource view like the Packages Explorer. We are going to present the following:
  • Loading content from a stream
  • Accepting changes made by others
  • Dealing with conflicts

Loading from a Stream

Bob wants to work on the project that Emily created. To do so, he needs to create his own workspace as Emily did. When Bob clicks Finish in the New Workspace wizard, he is prompted to load the contents of the workspace. On the first page of the Load wizard, Bob indicates that he wants to load Eclipse projects

Load Eclipse Projects

He can just click Finish at this point but clicking Next will show what content will be loaded.

Projects to be Loaded

As indicated above, Bob was prompted to load the workspace when he created it. To load an existing workspace, you can select Load from the context menu of the workspace in the Team Artifacts view.

Accepting Changes from Team Members

Let’s assume that after Bob loaded the project, he made some changes and delivered them in the same manner that Emily did. Emily can see that there are incoming changes in the Packages Explorer because the changed resources and their parent folders and projects are decorated with a blue incoming change arrow.

Incoming Changes

Emily now wants to accept those changes, which she can do in the Packages Explorer using the Team/Accept action from the context menu of the project. This will open a dialog that allow here to see what changes are incoming.

Accepting Changes

By clicking OK, she can accept all the incoming changes. If there are multiple incoming change sets, she can decide to accept only a subset of the those changes. However, this is not always possible if multiple change sets affect the same file. In most cases, she would just accept all the incoming changes.

What would happen if Emily had made changes of her own before accepting Bob’s changes? As long as the changes that Emily made are not in the same files as the changes Bob made, the accept will go smoothly. However, it is still recommended that Emily check-in her changes before accepting the changes from Bob. If she did have local changes that were not checked-in, she would get the following prompt when she accepted Bob’s changes.

Check-in Prompt

The advantage of checking in the changes is that a copy of Emily’s changes will then be uploaded to the server. This means that they are backed up in case anything goes wrong. For instance, if Emily had made a change in one of the files Bob changed, Bob’s changes would overwrite Emily’s. By checking in her changes, Emily will ensure that her changes will not be lost in this way and any conflicting changes can then be resolved, as described in the next section. Because of this, it is considered a best practice to always check in changes before accepted changes from the stream.

Dealing with Conflicts

One issue that needs to be addressed is how to handle cases where multiple team members need to edit the same file. There are basically two ways to deal with the situation: one is coined pessimistic while the other is called optimistic.

Pessimistic Approach

Using the pessimistic approach of handling concurrent edits to the same file by multiple team members means that only one team member is allowed to make changes to a particular file at any given time. Other team members need to wait until those changes are delivered before they make their changes. To support this workflow, a Team/Lock action is provided on files that will lock the file in the stream so that other team members will know that someone else is editing that file.

When a team member locks a file, the file is decorated appropriately in the Packages Explorer or any other resource based view.

A Locked File

Also, delivering a change to a locked file will result in a prompt indicating that the file is locked by another user.

A Locked File

However, when Bob delivers the change to the file he has locked, he will get prompted to unlock the file. If, instead of delivering the change, he decided to discard it, he could use the Team/Unlock action to release the lock on the file so other team members could edit the file.

In this way, a team can ensure that only one team member is making changes to a particular file at any given time.

Optimistic Approach

The optimistic approach to handling concurrent edits assumes that actual conflicting edits are relatively rare and team members will be able to merge conflicting changes safely when they occur. It turns out that, even if multiple users do makes changes to the same file at the same time, the tooling can, more often than not, automatically merge the changes because they occur in different sections of the file. For those cases where the concurrent edits touched the same part of the file, a compare editor can be used to manually combine or merge the conflicting changes.

Let’s assume that Emily and Bob are making changes to the same file. If Bob delivers his change, Emily will see that there is an incoming change that conflicts with the changes she has made, as indicated by the red two-way arrow decoration that appears on the file in her Package Explorer.

A Fiel Confluct Decoration

If Emily tries to Checkin and Deliver her change, her changes will be checked in but she will get a message prompt indicating that her change cannot be delivered until she accepts Bob’s change and resolves the conflict. When she accepts Bob’s change, she will get the following prompt, indicating that a conflict occurred.

Prompt after Accept

If she chooses to auto resolve the conflicts, the operation will attempt to merge the change automatically. However, if she chooses to resolve manually or if the operation couldn’t merge the change automatically, then the conflicts will need to be resolved from the Pending Changes view.

Pending Changes View

Emily will have several options for resolving the conflict. Here’s what the context menu of the conflicting file looks like:

Options for handling conflicts

Using these actions, Emily can:

  • Keep her changes and throw away Bob’s using Resolve with Mine
  • Throw away her changes and keep Bob’s using Resolve with Proposed
  • Attempt an automatic merge of the changes using Auto-Resolve
  • Open the changes in a compare editor using Open in Compare Editor
  • If she has edited the file and is happy with the contents, she can indciate that the conflict is handled using Resolve as Merged

Opening a compare editor would result in the following editor:

Compare Editor

It turns out that Emily’s and Bob’s changes do not conflict so she could simply have chosen to auto-resolve. She can do this from within the Compare editor by clicking on the Auto-Merge button. Once she does this, the conflict will be resolved and she can deliver her change. The Pending Changes view will then indicate that Emily’s change set contains a merge.

Change has been merged

Although the optimistic approach to handling concurrent edits can be used in many circumstances, there are situations when it is not recommended. Some of these include:

  • when the file is a binary file, since conflicting changes to binary files are difficult, if not impossible, to merge correctly.
  • when the file is used to generate other files, since the merging of conflicting changes would require a merge or rebuild of all generated files.
  • When the content of a file, while text, is complicated enough that it is not easily understood without the proper tooling to interpret it.

Understanding Jazz SCM Workspaces

One of the ways that Jazz SCM differs from traditional SCM systems like CVS and SVN is through the use of what is referred to as a repository workspace. In Jazz SCM, users can have one or more repository workspaces which represent their own personal work area on the server. As we saw in the examples presented in this article, when a user wants to make some changes in the RTC Eclipse client, they will load the contents of one of their repository workspaces into their Eclipse workspace and the changes they make need to be checked into a user’s repository workspace before they can be delivered to a stream.

The following shows the relationship between Emily’s Eclipse workspace, her repository workspace, and the stream that her team uses.

Eclipse and Repository Workspaces

Her Eclipse workspace manages the code she has loaded onto her local filesystem so she can makes changes, test, etc. When Emily makes some changes to her code, the changed files will appear under the Unresolved node in the Pending Changes view.

Unresolved changes

In the example for section Making Changes in a Stream, we showed how Emily can deliver her unresolved changes to a stream using the single action Check-in and Deliver. However, she could instead choose to only check them in using the Check-in action if she wanted to have her changes backed up on the server but did not want to make them available to her team members through the team’s stream. She can choose when and how often she does this but there is no reason not to do it fairly often and she will definitely need to do it before she accepts any changes from the stream, as illustrated in section Accepting Changes from Team Members. Another advantage of checking in changes before they are to be delivered to the stream is that she can add a comment to the change set that contains the changes and she can also associate a work item with those changes, if she desires.

Outgoing Changes

Once she has completed working on a particular unit of work and wants to make that available to her team, she can then deliver the changes to the stream.

As you can see, having a repository workspaces provides some benefits, some of which are:

  • you have a backup of your work.
  • other members of your team have access to your work-in-progress
  • you can make associations between your current work and other articfacts on the server (e.g. work items)

Also, repository workspaces are an essential part of some of the main multi-stream workflows supported by Jazz SCM as described in the article Multiple Stream Development.

The Next Step

In this article, we presented some simple workflows for using Jazz SCM and introduced some of the basic concepts that differ from other SCM systems. Some additional articles you may find helpful are:

Some of the articles were written for RTC 2.0 but the concepts still apply to RTC 3.0.

About the author

Michael Valenta is a member of the Jazz SCM development team. Prior to that, he worked on the Eclipse open source project.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.
Was this information helpful? Yes No 18 people rated this as helpful.