IBM Rational Jazz Source Control and Build Management Tool Tutorial

The Jazz Source Control is a repository in RTC, which can hold the source code and any other artifacts like documents or HTML files or any text files. And Jazz source control management comprises of several components like component, changeset, stream, repository workspace etc.

In this tutorial, we will learn more about the components and functions of Jazz Source control along with Build Management module of RTC. 

NOTE: This tutorial has many images so allow it to load properly. 

In this tutorial we are going to take an in-depth look at “Jazz Source control” using “IBM Rational Team Concert” and it is based on version 6.0.2.

Introduction to IBM Rational Team Concert

As mentioned above, IBM Rational Team Concert (RTC) is one of the key components of IBM Rational CLM solution.

Today with ALM solution, project teams are looking at a solution which is integrated with execution. IBM Rational Team Concert helps Project Managers and the Developers to maintain the few artifacts within one single repository.

The artifacts are:

• Work Item Management
• Project Planning (Supports Agile Scrum or Waterfall)
• Software Configuration Management (SCM)
• Build Management

All the above components are well integrated to provide complete traceability of work that is performed from a development perspective. Now, let’s take a look at some of the concepts involved in Jazz SCM.

Any development team consisting of multiple members work with a large base of source code for an application that is being developed. Each team member works with the same source code, changing one or more files to work on a new feature or to fix a defect. The team member checks if the changes are correct, and then shares those changes with the rest of the team to a common area.

At the same time, other team members will work on the tasks assigned to them and make changes to the source code. So a source control tool helps in organizing the team’s source code or documents, tracking them and sharing changes to a common area thereby assisting the team to complete the tasks assigned to them.

In my previous tutorial, we saw how work items (like Story, Task, Defect etc.) hold important project information. In extension to that, these Task items will now be linked to the changes in source code.

Components of Jazz Source Control

The Jazz Source Control is a repository in RTC, which can hold the source code and any other artifacts like documents or HTML files or any text files. This repository is managed by Jazz Team Server and is accessed using a URL which we will see in this tutorial.

Let’s look at the components involved in Jazz Source Control and how we will make utilize it.

#1) Change Set

A Changeset is a collection of file or directory changes which are typically grouped together. In the following sections, you will see how multiple changes to source code are grouped into a changeset.

#2) Stream

A stream is used to store entire team’s changes. Typically when all the team members make changes to the source code, they commit or deliver the changes to the projects mainstream. Before they deliver the changes, they have to assign the changes they made in the source code or any artifacts to a Task work item which a team member is assigned to.

#3) Component

A component holds all of the artifacts which include the source code and any other project artifacts.

#4) Repository Workspace

A repository workspace is an area where you can view and modify version controlled artifacts. The creation of Repository Workspace is a must for every member working on source control artifacts.

So if there are 10 members working on Jazz Source Control repository then each one of them should create at least 1 repository workspace to work on version-controlled files.

How Do Jazz Components Work?

Let’s look at the workflow of how the above components work together as integrated.

The flow starts from left as shown below with the first developer doing the changes in his development IDE like Eclipse or Visual Studio.Net to the source code and then checks-in the changes to the repository workspace and DELIVERS the changes to the projects main shared work area called the Stream.

The second developer while working on his source code changes will ACCEPT the changes into his own workspace. While doing so if there are any conflicts in the same line or multiple lines then he has to manually merge those changes.

Jazz SCM Usage

In order to work on the Jazz SCM, the users must do the following. I have taken the above scenario and explained with 2 users working on the same code base. In this tutorial, I am using a sample Java web project code in Eclipse IDE. The same procedure can be followed in Visual Studio.NET for .NET code base as well.

User 1 Activity

1. User1 shares the project to the Jazz source control
2. User1 makes changes, checks-in and delivers the changes to the project STREAM. Remember that there is no explicit check-out required. As the user makes changes, it is considered as checkout.

Let’s now look at how the above 2 steps are done in Eclipse IDE as User1. So the first user logs into the RTC project area and switches to the Java perspective.

A sample HelloWorld Maven web project is created and it will be uploaded to Jazz source control for the team to work on.

(Note: Click on any image for an enlarged view)

Share project to Jazz Source Control as User1

#1) User1 logs into the RTC project area and opens the Java perspective where the Maven project will be visible in the Package Explorer view. To share the project to Jazz source control right click on the project and then select Team=>Share Project

#2) Select Jazz Source Control and follow the remaining steps to complete the upload to the Jazz repository

Create a new repository workspace for User1

Select the Project stream. Remember, that the stream and component were created by default when the RTC project area was created. You can create your own stream and component as well. For this exercise, we will use the default ones created already.

Ensure that the project to be shared with Jazz source control is selected. Click Finish.

#3) You can now see that the User1 Workspace is associated with the Maven project in the Package Explorer which means the project is now under Jazz source control repository.

#4) The project is shared to Jazz source control but it is not yet visible to other team members. For this, a Deliver operation should be done. Go to Pending Changes View and you will see an Outgoing folder. Right-click on that Outgoing folder and select You can see change set under the Outgoing folder. It can be a comment or a Task work item assigned to the developer

#5) The project is now available in the project stream. So other users can now create a repository workspace and do changes to the version-controlled project in their own local Eclipse workspace

User2 Activity

As User2 will be accessing the repository for the first time, the following actions need to be done.

• User2 logs into the RTC project area
• Creates a repository workspace and downloads the project uploaded by User1
• Initially, the project will be downloaded to the local machine from the jazz repository for doing changes. Hence for the first time, the User2 need not ACCEPT any changes. But subsequently, the user will need to ACCEPT the changes
• User2 does the changes and then delivers those changes to the stream.

#1) User2 creates a repository workspace as shown below. Right-click on the stream and select New =>Repository Workspace

Enter a name such as User2_Workspace and then click Next to follow the remaining steps.

Click Finish to start downloading the Maven project from the repository to local machine eclipse workspace.

Click on Finish

#2) Now you can see the project which is linked to User2_Workspace

#3) Open the index.jsp file and make some changes. Remember there is no checkout and this change is done as User2. After making changes to the file, SAVE the file. At the bottom of Pending Changes view, you will find an Unresolved folder.

#4) If in case you want to Undo the changes, then you can do so by right-clicking on the Unresolved folder and select If that is not required, then proceed to the next step.

#5) Now right click on the Unresolved folder and select Check-in All.

#6) Assign a TASK work item to the changeset and deliver the changes to the stream. Right-click on the changeset which shows as <Enter a Comment> and select Related Artifacts =>Associate Work Item

Select the Task work item assigned to User2 and click OK

#7) You can now see the changes associated with the Task work item and can now deliver the changes to the stream.

#8) You can also view the History of changes to any file. Right-click on the file in the Package or Project Explorer and select Team=>Show History

#9) You can revert back to any previous version by right clicking on any previous Version ID and selecting Load. After this, you will need to check in and Deliver as usual.

User1 Activity

Back in the User1 workspace, since User2 has delivered the changes, User1 will now see the changes as Incoming. Right-click on the Incoming folder and then select Accept.

The changes done by User2  is now populated in the User1 workspace. So User1 workspace is up to date on the Jazz repository.

As User1, now modify the second line in the <body> tag to produce a conflict assuming that even User2 does a change on the same line.

As usual save the file, Check-in All, Assign to a Task work item and Deliver the changes to the stream.

User2 Activity

User2 will see the change in Incoming folder. But at same time User2 also modifies the same line.

Save the file. Right-click on the unresolved folder and select Check in All

Assign a Task work item before Deliver. Right-click on the changeset titled <Enter a Comment> and Associate a Work item. Click on OK once done.

Right-click on the Outgoing folder and select Deliver

You will notice that the changes cannot be delivered, as there is a conflict. We need to resolve the conflict and then proceed with Deliver. Click on OK

To resolve the conflict, first of all, accept the Incoming changes. Right-click on the Incoming folder and then select Accept

In the Auto, Resolve box select the Resolve Later option

Double-click on the index.jsp file which is shown in the Unresolved folder.

Right click on the index.jsp file and select Resolve with mine. This option will retain the changes done by the current user which is User2. Resolve with Proposed will update the file with the incoming changes done by User1.

Click on Yes to proceed and then select the option Resolve as Merged on the right-hand side.

Now right click on the change set below the Outgoing folder and then select Deliver

Now login as User1 and Accept the changes from the Incoming folder.

Build Management

IBM Rational Team Concert supports build management as a logical extension to the version control activities which was explained above in this tutorial. Multiple team members deliver their changes frequently preferably on a daily basis and each of this integration is verified by an automated build to detect any defects or errors as quickly as possible. This leads to the concept of Continuous Integration. The automated build is normally done on a dedicated build server and not on a developer machine.

To get started with build management activities in RTC on the build server, you will need to download and install Build System Toolkit using the IBM Installation Manager. For version 6.0.2 it is available in the Jazz.net download site.

The installation instructions can be found on this page.

To define and run any build you will need the following 2 build artifacts

• Build Engine which helps to run the defined build. This is available once the Build toolkit is installed
• Build Definition which helps to identify any build script like ANT or Maven

All of the Build Management actions are done on a dedicated build server and a separate repository workspace has to be created for the build. Do not use any existing developer repository workspace.

Starting Build Engine

In RTC, create a Build engine as shown below. Right-click on the Build Engines folder and then select New Build Engine

Click Next>

Enter an ID and select Jazz Build Engine and click on Finish

Click on Save in the Build Engine screen

Start the Build Engine

To start the Build Engine, go to the directory where it is installed and then run the jbe.exe program found in the build toolkit eclipse directory

D:IBMTeamConcertBuildbuildsystembuildengineeclipse

Run the program from a command prompt as follows

 

Replace the values as per your server details

Create a Build Definition

Right-click on the Builds folder and select New Build Definition and click on Next

Enter an ID and select Maven – Jazz Build Engine as the build template. Click Next

Select Jazz Source Control and select Finish

In the Overview Tab of the Build Definition, add the Build Engine created earlier and then click OK

In the Jazz Source Control TAB select or create a new Build Workspace and enter a load directory. This is the directory where the project will be downloaded and the build will be done to generate the WAR file. Each time when the build is done, it will be deleted and the latest project content will be downloaded for the build.

Just below in the same TAB, you can see the option where latest changes will be accepted before any new build and only if there are changes the build will be done.

In the Maven TAB, enter the location to the pom.xml file. The project will usually be downloaded to the load directory. So the pom.xml location would be D:LoadDirHelloWorld-Maven

Enter goal as install.

Enter Maven home directory without the bin

Save the Build Definition.

Request a build

In the Team, Artifacts view right click on the build definition and then select Request Build.

Click on Submit.

The Build result is shown as completed successfully and WAR file generated in target directory will be shown in the package explorer.

Conclusion

In this tutorial, we have seen how to use version control module within IBM Rational Team Concert and how work items play a very important role in traceability of the source code.

Most important part of the SCM activity in RTC is that it is completely integrated with the Build Management which defines the concept of Continuous Integration.

We also learned about the Build Management module of RTC which accepts latest changes from the Jazz SCM repository and performs the build.

In my next tutorial, we will see an extension to this build activity which is – Auto Deploy using another IBM tool called IBM Urbancode Deploy.

Stay tuned!!!

Let us know your thoughts/suggestions in the comments section below.