Using Rational Team Concert for a software engineering class project, Part 2: Introduction to iteration plans and Jazz source control

In Part 2 of this tutorial series, we introduce you to the source control mechanism and iteration planning tools that you need for the evolution of your project.

This two-part tutorial describes some of the major concepts of IBM® Rational® Team Concert™, such as work items, teams, source control, and iteration plans, and how these concepts can be used in developing a small software project using an agile process in a class setting.


Thomas Fritz (, Postdoctoral Researcher, University of British Columbia

author photoThomas Fritz received the Diploma degree in computer science from the Ludwig-Maximilians-University Munich, Germany, in 2005. He received the PhD degree in computer science from the University of British Columbia (UBC) in 2011. He has experience working as an intern with several companies, including the IBM OTI labs in Zurich and Ottawa where he worked with the Jazz work item and source control teams. He has taught the undergraduate introductory course to software engineering in the department of computer science at UBC and is currently a postdoctoral researcher at UBC. His research focuses on how to help software developers better manage the information and systems on which they work.

Meghan Allen (, Lecturer, University of British Columbia

author photoMeghan Allen received her BSC and MSc degrees in computer science from the University of British Columbia (UBC) in 2001 and 2006. She has experience working as a software developer where she used team coordination tools "in the wild." Since 2007, she has been a lecturer for the department of computer science at UBC, where she has taught a variety of undergraduate courses including the introductory course in software engineering that uses Rational Team Concert.

27 September 2011

Also available in Vietnamese Spanish

Software development teams must undertake activities such as breaking down a development project into manageable tasks, creating and changing source code, communicating with fellow developers, and managing teams. IBM Rational Team Concert collaborative project management software supports many such engineering activities and thus can form the cornerstone of software development projects. This tutorial shows how you can use Rational Team Concert to keep track of the evolution of the project through its source control mechanism and a defined software development process with iterations.


Part 1 this two-part tutorial introduced you to the fundamental concepts of IBM® Rational Team Concert™ collaborative software development project management software. It focused mostly on teams and work items. This part shows how you can use Rational Team Concert to keep track of the evolution of the project through its source control mechanism and a defined software development process with iterations.

Each student (in the example in Figure 1: Thomas), has a separate local workspace, the same way that you have a workspace in Eclipse on your local machine. Each student also has a repository workspace on the server (in Figure 1: Thomas's Repository WS, where WS stands for workspace), which serves as a safe copy for all of the project code that particular student has checked in.

Agile and scrum processes

You'll understand this article better if you're also familiar with agile software development methods and the scrum project management process. See the Resources section for a list of sites and articles that will give you a good orientation.

Note: If you are familiar with the Concurrent Versions System (CVS), you can think of your repository workspace as your very own CVS repository, into which only you will be checking in code.

Apart from your own repository workspace, you also need to share code with your teammates. For this purpose, each team has its own a data stream on the server.

After you change the code of the project, save your changes by checking them into your repository workspace (check-in). When you're ready to share these changes with the team so that everybody can see them, you just deliver them to the stream. After they are delivered, your teammates will see that there are incoming changes, and they can accept them into their workspaces. When they accept them, your changes will be in their repository workspaces, as well as their local workspaces. So the stream serves to share and to save your team's code, and changes flow back and forth among the local workspace, the repository workspace, and the data stream.

Figure 1. Basic workspace and stream setup for a project
Diagram of the accept and deliver workflows


The act of moving changes to code from a stream to your repository workspace.
Change set
Several changes to various source files. A change set is a unit of changes that should be associated with a single work item.
The act of moving changes to code from your repository workspace to a stream.
Flow target
The flow target of a repository workspace indicates the stream to which deliver and accept operations are performed.
Local repository
The copy of the code that is on your hard drive, either in the lab or at home.
Product Backlog report
A prioritized list of product backlog items in the form of user stories. It captures all desired functionality for a particular release.
Repository workspace
Your own source-controlled backup, which is on the Jazz server.
Sprint Backlog report
A list of sprint (iteration) backlog items broken down into specific tasks that the scrum team is committed to complete in the sprint.
Short for data stream, the location where teams exchange code.
User story
Text description of a requirement that is written from the user's perspective and expresses what a user wants.

Data streams

Before you can start using Jazz source control, you need to create a data stream. A data stream is used by a team to share source code. Therefore, you will need only one stream for your entire development team.

Create your data stream

Remember: your development team needs only one stream. So the first team member to complete this part of the tutorial should create the stream.

To check whether it has already been created, make sure that you are using the Work Items perspective, and then select the Team Artifacts view and, under the Project Area item, expand Source Control (for this example: CPSC 310 - Spring 11 > Source Control).

If you see a stream for your team, it has already been created and you can skip to the Repository workspace section.

If the stream doesn't exist yet, follow the rest of the instructions in this section to create it:

  1. From the Work Items perspective, open the Team Artifacts view and expand your project area (CPSC 310 – Spring 11 in this case).
  2. Right-click the Source Control node, and select New > Stream to open a stream editor.
  3. In the Name field, type your stream name.
  4. Then click Browse, and select your development team.
  5. (Optional) You can add a short description of this stream.
  6. You then need to add a component to this stream. In this example, each development team will use just one component, but your component can contain multiple Java projects.
    1. To add the components, in the Components section, click New.
    2. Enter a name for your component, and click OK.
  7. Click Save to save this stream.

Repository workspace

Before you start using Jazz source control, you will need to set up your repository workspace. As we mentioned previously, the repository workspace lives on the Jazz server and serves as a backup copy of your local workspace. However, it is more than a simple backup copy; it is a version-controlled copy. It keeps track of all changes that you made, and you can always revert to an earlier version if things go wrong.

Create a repository workspace

Because all team members should have their own repository workspaces, you need to complete this step for your own workspace:

  1. First, make sure you are using the Work Items perspective.
  2. From there, select the Team Artifacts view, and, under the project area node, expand the Source Control node (for this example: CPSC 310 - Spring 11 > Source Control).
  3. Locate your stream, right-click it, and select New Repository Workspace.
  4. For the repository workspace Name field, enter Your Name Repository Workspace (replace Your Name with your own name, naturally)
  5. Click Next, select Public, and click Next again.
  6. Make sure that the component created in the previous section is selected, and click Finish.

If the Load Repository Workspace wizard opens, you can select Find and load Eclipse Projects, and then click Finish.

  1. In the Team Artifacts view, you can now expand the My Repository Workspaces to see your newly created repository workspace. Double-click it, and you should get the editor screen shown in Figure 2 (except that your flow target should be your team's stream).
Figure 2. Repository workspace editor
Details, Components, and Flow Target sections

Rational Team Concert source control

Your environment is now correctly set up to use source control. This section of the tutorial shows you how to use source control to back up and exchange your code.

Create the project

One person on your team needs to create the Java project that you will be working on.

  1. Switch to the Java perspective, and open the Package Explorer.
  2. If you can see the project (HockeyPool in this example), one of your team members has already created it, so you can skip ahead to the Exchange source code with your team section. If you don't see the project, you will need to create it.
  3. After you have created the project (if it didn't exist already), right-click the project name and select Team > Share Project,
  4. Select Jazz Source Control, and click Next.
  5. Select the component in your repository W=workspace (created in the Create your data stream section, previously), and then click Finish.

To share the project with your team members, you must check it in to your repository workspace and then deliver it to the stream.

  1. To check in your project, right-click the project name and select Team > Check-in.
  2. Now, to deliver the project to your team's stream, right-click the project name and select Team > Deliver.

About checking in files

Remember: every time you check in a file, it automatically gets backed up to your repository work space. Therefore, you can work from your laptop, from home, or from any other computer.

Exchange source code with your team

Edit code

To see the effect of code changes, make some changes to the code, such as adding a new class or changing an already existent class or method.

Look for your changes

  1. After you have modified some of your code, look for the yellow background on the file's icon. The yellow background indicates that you have made changes that have not yet been checked in to your repository workspace (Figure 3).
Figure 3. Indication of changes in the Package Explorer view file shows yellow background
  1. To check in these changes, right-click the file, and then select Team. > Check-in.

Now your changes have been saved in your repository workspace.

  1. When you're ready to share your changes with your team, deliver your changes.
  2. Look for the Pending Changes view (probably at the bottom of your screen).

Tip: If you can't find a view, just select it: Window > Show View.

The change symbol change symbol icon (triangle) identifies a change set, which includes all of the files that you have modified since you last delivered your code to the stream. If you want to view these changes, you can double-click on any Java file and a Difference editor will appear, showing which lines were inserted and which were deleted.

Associate your change set with a work item

In Part I of this two-part tutorial (see the "View more content in this series" link), we mentioned that every task you perform needs to correspond to a work item. This is especially important when editing code. So the changes that you just made to the code must correspond to a work item.

  1. Therefore, create a task and name it My first code edit.

Note: Normally, the work item should usually be created before you start editing code. This work item will be a task when a new feature needs to be implemented or a defect if you are correcting a bug.

  1. Now, in the Pending Changes view, right-click the change set, and select Associate Work Item.
  2. Select the corresponding work item (you might have to type in the name), and click OK.

You should now see the description of the work item rather than <Enter a Comment> beside the change set.

Tip: If you specified that you are currently working on a work item (by changing its status to Start Working in the work item editor), it will be automatically associated with your change set, and you will not have to go through that procedure.

Deliver the change set

To deliver your changes, right-click the change set, and select Deliver and Resolve Work Item.

This will open a dialog window where you can add comments to the work item. The changes will now be available to every member of your team.

Deliver only changes that compile correctly and pass the tests. If the changes that you deliver do not compile, you will slow down the whole team.

If delivery fails

The delivery operation might fail if one of your teammates delivered changes to the same project before you. This is because the system requires that you accept their changes before you can deliver yours. This ensures that you are all working on the same version of the project and that potential conflicts are always resolved.

Accept changes

To accept changes, click the Accept icon Accept icon (triangle with downward arrow above).

This could generate conflicts if the changes appear in the same file that you modified. Don't worry, because Rational Team Concert will launch a special editor so you can resolve these conflicts.

Product and Sprint Backlog reports and user stories

A software development process is usually divided in a number of iterations (also known as phases). The nature of these iterations will change based on the process model chosen by the team, but the concept of iteration remains. This concept is an integral part of Rational Team Concert, and one way in which it is visible is through Iteration Plans.

In this case, we will use a Scrum process with one major release and two sprints (two iterations). If you are not familiar with Scrum, you should quickly read up on Scrum on the web to understand the basic concepts.

Create a Product Backlog report

A Product Backlog contains all desired functionality for a particular release in the form of a prioritized list of Product Backlog items and user stories. It is used by an entire team.

Tip: Any member of the team can create a Product Backlog. But make sure that only one of you is responsible for creating it, because you will have duplicates, otherwise.

  1. From the Team Artifacts view, select Plans > All Plans > Main Development > Release 1.0, right-click and select New > Plan.
  2. In the dialog window (Figure 4), name your iteration plan.
  3. Make sure that the Owner is your team and the Iteration is Release 1.0.
  4. Then expand the Advanced Options, select Product Backlog in the drop-down menu, and click Finish.
Figure 4. New Plan dialog window
Create Plan view for creating an iteration plan

Create user stories

Now, add the user stories for your project to the Product Backlog Plan.

  1. When you open your Product Backlog Plan in the editor and go to the Planned Items tab, right-click on Release 1.0, and you can add your user stories by selecting Add Work Item > Story.
  2. Fill in the summary of the user story in the text field.
  3. Save the plan so that the user story is saved, too, and double-click the user story to open it in the editor.
  4. Now add the relevant information, such as the story points (if you already decided on them), the priority, and the acceptance criteria (under the Acceptance Test tab).
  5. Also, make sure to file the user story against your team: select your team category in the Filed Against drop-down menu (if the team category does not appear right away, click More, and then you should be able to find it).

You do not need to specify an owner yet.

Create a Sprint Backlog report

After the sprint planning meeting in which you decided on the user stories that you are going to include in the sprint, one of your teammates has to create the Sprint Backlog (basically, an iteration plan). Again, make sure that only one of you is responsible of creating it. Otherwise, you will have duplicates.

Also, you must make sure to create the Sprint Backlog in the appropriate sprint.

  1. For the first sprint, select All Plans > Main Development > Release 1.0 > Sprint 1 (1.0), right-click it, and create a new plan.
  2. Name your Sprint Backlog, and don't forget to select your team as the owner.
  3. Select the sprint (Sprint 1 for the first sprint) in the iteration, and, in the Advanced Option section, select Iteration Plan.

Each Sprint Backlog needs a short description for the main outcome of the sprint.

  1. Under the Overview tab, click the Start Editing link, and briefly describe what your team wants to do in the sprint.
  2. Click Save.
  3. To move user stories from your Product Backlog into your Sprint Backlog, in the Planned Items tab, open your Product Backlog and drag the user stories from the Release 1.0 section to the Sprint 1 section ().

    1. If you do not see the Release 1.0 and Sprint 1 sections in the Planned Items tab of the Product Backlog, under "View as," select Edit.
    2. Then, under Grouping, select Iteration.
    3. Save this, and the Product Backlog should now contain sections for the release and all sprints.

Dragging the items into the appropriate sprint will automatically associate them with the sprint and add them to your Sprint Backlog. Now, if you open your Sprint Backlog again and go the Planned Items tab, you should see the stories that you associated with the sprint.

Create sprint tasks

Now that you have selected the user stories for your first sprint, you need to refine the user stories and create the actual tasks that you will work on.

  1. First, open the Sprint Backlog. For now all user stories should be in the Unassigned section.
  2. Right-click on a user story and follow Add Work Item > Task to create a task.
  3. Fill in the Summary field, and click Save to save the task.
  4. Open the task by double-clicking it, and then fill in the other information.
  5. If the task is part of a user story, make this relationship explicit by adding the user story as its parent (either by adding a parent in the task or by dragging the task onto the user story).


  • Make sure to file your user stories and your tasks or defects against your team (choose the proper category in the Filed Against field). Otherwise, the story, task, or defect will not show in your Product or Sprint Backlog reports.
  • When you decide to start working on a task or a user story, make sure to change the owner to yourself, so that everyone on the team can see that you are working on it.

At the end of an iteration, all of the work items contained in the corresponding Iteration Plan must be resolved. If you have work items left, either move them to the next iteration or resolve them by, for example, indicating "Won't fix" in the appropriate field.

Because the Iteration Plan is such a great tool, you can make it part of your favorite pages. Just right-click on it in the Team Artifacts view and select Add to Favorites. It will now appear in your Favorites folder.

What you have learned

After completing this tutorial, you should have a basic understanding of the following important concepts related to Eclipse and Rational Team Concert:

  • The difference between your local workspace and the repository workspace
  • The concept of a stream to share code with other members of your team
  • How to create a stream and a repository workspace
  • The concept of a change set
  • How to associate a work item with a change set
  • How to check in code to your repository workspace
  • How to accept and deliver changes between you and your teammates
  • How to integrate your changes with your project teammates'
  • That a software development process is a series of iterations
  • How to create a Product Backlog and a Sprint Backlog
  • How to add user stories to a Product Backlog and to a Sprint Backlog
  • How to write the overview of a Sprint Backlog
  • How to add tasks to a Sprint Backlog and how to manage them



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Using Rational Team Concert for a software engineering class project, Part 2: Introduction to iteration plans and Jazz source control