< Previous | Next >

Lesson 6: Managing source code

The source control component handles the storing, retrieving and sharing of source code and other artifacts in your project. IBM® Engineering Workflow Management source control (SCM) support is easy to use for several development scenarios but it is different than regular file-based SCM systems. So let us start with a quick overview of the usage model.

About this task

You can benefit from Engineering Workflow Management (EWM) source control's ability to track and version your changes, whether you are ready to share those changes with your team or not. Accordingly, as a user you have your own private repository workspace which stores the changes you've made, regardless of when you decide to make them available to your team. Sometimes it will be only a couple of hours before you decide to share your changes; sometimes it will be a day, or longer. The key is that your changes are in the repository and you decide when to make them available to your team. When you load your repository workspace, the files and folders in it are transferred to your sandbox (a directory in your computer's file system). In Eclipse, the initial default for the sandbox is the same directory as your Eclipse workspace. To push a change from your sandbox to the repository workspace you check in the change.

A stream is used to store the team's work. When you want to make your changes available to your team, you deliver them from a repository workspace to a stream. When you want to incorporate other team members' changes, you accept them from the stream. You can also accept changes directly from another repository workspace, allowing for fine-grained sharing of changes between team members. For example, two team members might collaborate on a small bug fix; or, if someone starts a change and goes on vacation, another team member can continue the work and then deliver it later.

Source Control workflow

All changes you make in your repository workspace are tracked within change sets. Each change set is composed of a collection of explicit, primitive changes to one, or more files or folders. A change set can also carry a comment and the reason the changes were made, typically by referencing the relevant work item. The source file base is built up from nothing but the steady accretion of change sets, each one building on everything that has come before it. Each repository workspace or stream is based on a sequence of change sets.

Let us start making changes and learn how these concepts can be used in day to day work.

Creating a Repository Workspace

The first step is to find the stream for your project area. The stream is where you share your code with your team.


  1. From the Team Artifacts view, expand the Prelude project area, and expand Source Control; then expand Prelude Stream (Prelude) to view the component. If no entries display under Source Control, look at the Customize My Filter drop-down noted on the screen capture. Open the drop-down and make sure All Team Areas is selected.
    Note: When you are a member of multiple teams, you can find customized filters useful.

    Streams and repository workspaces can be partitioned into separate components. Because each component has its own history, breaking a product into components is useful for teams that build layered software in which the pieces evolve semi-independently and are deployed separately. Simple repository workspaces and streams consist of a single component. In our example, the Prelude Stream has just one component (called Default Component) which contains our files and folders.

    Default Component Stream of the Team 1 Stream

  2. Select the stream for your project team, labeled Prelude Stream (Prelude).
  3. Right-click; then click New > Repository Workspace.
  4. In the New Repository Workspace wizard, on the New Repository Workspace page, in the Repository Workspace name field, type Chris on Prelude and click Finish.
  5. On the Load Repository Workspace page, ensure that Find and load Eclipse projects is selected and click Finish. This action creates and loads your new repository workspace into your sandbox. The load completes quickly, since there is no code in the stream yet.
  6. When a repository workspace is loaded, it displays in the Pending Changes view. If the Pending Changes view is not visible, click Window > Show View > Pending Changes.
  7. Optional: If you were able to complete the team invitation tutorial, then you completed one of the work items created when your project area was initialized. Run your Open Work Items query again and note the [Joining a Team] Create a Repository Workspace work item. You can now open that work item and resolve it just like you resolved the Define team members work item earlier.


Loaded repository workspaces are special because whenever you change a loaded file or folder in your sandbox, the changes are tracked and shown in the Pending Changes view. Here, you can manage your changes and perform common tasks such as the following:
  • Check in changes to your repository workspace.
  • Organize changes into change sets.
  • Undo changes you have made.
  • Associate change sets with work items.

You will see a lot more for the Pending Changes view in the next sections, as it is really at the center of a developer's day-to-day work.

Authoring code

After you have joined a stream, you can write code and produce the artifacts that make up your project.

About this task

If you have some Java™ packages from a small project you would like to try with EWM, you can import those projects into your sandbox now from the Package Explorer view by selecting the Import option from the menu. But if you do not have any interesting code to start from, you can create a simple Java application or create a simple project containing a single text file.


  1. For help creating a simple Java application in the Jazz client, click Help > Cheat Sheets.
  2. In the Cheat Sheet Selection dialog box, expand Java Development category, click the Create a Hello World application. Click OK. The cheat sheet displays in your Jazz client window and guides you through creating a simple Java application. For more advanced help see the Eclipse Java Development User Guide.
    Note: The authors of this tutorial created a simple Java project called Hello Prelude.

Putting your code under Jazz Source Control

After you have either imported or manually authored some code in your sandbox, you can check in your code to your repository workspace on the server and share your project with your team.

About this task

Check-in is the process of moving code from your sandbox into your repository workspace. The term for moving code from your repository workspace into the stream to be shared with your team is deliver. You can change your Jazz Source Control preferences to specify automatic check-in. You can also work disconnected and check in later when reconnected.

To check your project into Jazz Source Control:


  1. Open the Java perspective. If this is not the current perspective, click Window > Open Perspective > Java.
  2. From the Package Explorer view, select the Hello Prelude project.
  3. Right-click; then click Team > Share Project.
  4. On the Select Component page, ensure that the chris@localhost repository connection is selected from the drop-down list at the top of the page. Also, make sure Select a component or folder in an existing repository workspace is selected. Expand Chris on Prelude and select the Default Component. Click Next.
  5. Although you probably do not need to change anything, on the Review Ignored Resources page, verify or complete the resources to ignore for sharing. Click Finish. Your code has now been checked into your repository workspace, but has not been delivered to the stream.The Pending Changes view with outgoing changes pending
  6. Optional: Switch to the Pending Changes view. From the Java perspective, click Window > Show View > Pending Changes. The view should have been open already when you loaded and shared your project. If you expand the Default Component, you can view a change set for the project you shared. We have tracked the share operation and the corresponding changes have automatically been checked in to the repository workspace.
  7. Optional: The change set already has the comment Share projects associated with it. To change the comment, or add comments to future change sets that do not automatically get a comment, right-click the change set; then click Edit Comment. In the edit pane, type the comment and click Enter.
  8. Optional: To navigate the component directory structure, in the Pending Changes view, right-click on the Default Component; then click Show > Repository Files. In the Repository Files view, you will see the project you have shared.
  9. Optional: To examine the history of your repository workspace, in the Pending Changes view, right-click on the Default Component; then click Show > History . The History view lists both the initial change set from when the component was created and the second change set you created. To explore the contents of a change set, double-click a change set. The Change Explorer view opens and allows you to browse the files in the change set.

Delivering your changes to your team

In this section, you will see the change set representing the code you authored. Then you will associate your change set with an existing work item. Finally, you will deliver your code to the stream.

About this task

All of the changes you have made are stored in your repository workspace in the repository.
Note: You must be a project team member and have an appropriate license to deliver changes to a team stream. In this example, Chris is a member of the Prelude project team and has a Developer license, which permits him to deliver changes to the stream.

To deliver the changes and make them available to the rest of the team:


  1. In the Pending Changes view, right-click on a change set; then click Related Artifacts > Associate Work Item
  2. In the Select Work Items dialog box, clear the My assignments only check box.
  3. In the Containing id or text field, type share. The work items that contain the word share in their summary will display.
  4. Select the work item labeled Share code with Jazz Source Control and click OK. This action creates a connection between the code you authored and the work item that you resolved in doing so.
  5. To deliver and resolve the work item, in the Pending changes view, complete the following steps:
    1. Right-click on the change set; then click Deliver and Resolve Work Item.
    2. In the Add a comment to the work item pane, type a comment to add to the work item.
    3. Click Finish.
    The work item is resolved and your code has now been delivered from your repository workspace on the server to the project area's stream, where it is now accessible to the rest of the team.
  6. Optional: Refresh the History view. The view shows that the change set has been associated with the work item.
  7. Optional: In the Team Artifacts view, in the Prelude Stream, right-click on the Default Component, then click Show > History. The History view displays your change set in the stream.
  8. Optional: In the History view, to open the work item associated with the change set, right-click on the change set, then click Related Artifacts > Open. The work item is Done and contains a link to the change set that you created for this work.

Lesson checkpoint

In this lesson, you learned the basics of EWM source control.
< Previous | Next >

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki