< Previous | Next >

Lesson 6: Source control

The source control component handles the storing, retrieving and sharing of source code and other artifacts in your project. Rational Team Concert™ source control (SCM) support is easy to use for a variety of development scenarios but it's a bit different than regular file based SCM systems. So let's start with a quick overview of the usage model.
In Rational Team Concert, we want users to benefit from SCM's ability to track and version your changes, whether or not you are ready to share those changes with your team. 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 Eclipse workspace on your computer. To push a change from your Eclipse workspace 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 wish to incorporate other team members' changes, you accept them from the stream. Note that 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 has to go on vacation, another team member could 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's 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 team 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 the Team 1 Stream to view the component. If no entries display under Source Control, take a look at the Customize My Filter dropdown noted on the screen shot. Open the dropdown and make sure All Team Areas is selected.
    Note: When you are a member of multiple teams, you may find customized filters very 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 Team 1 Stream has just one component (called Default Component) which will contain our files and folders.

    Default Component Stream of the Team 1 Stream

  2. Select the stream for your team area labeled Team 1 Stream (Team 1).
  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. This action creates and loads your new repository workspace into your Eclipse workspace. The load should complete quickly, since there is no code in the stream yet.
  5. 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.
  6. 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 in that whenever you change a loaded file or folder in your Eclipse workspace, 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've made.
  • Associate change sets with work items.

You'll 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.
If you have some Java™ packages from a small project you would like to try with Rational Team Concert, you can import those projects into your Eclipse workspace now from the Package Explorer view by selecting the Import option from the context menu. But if you don't 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 Eclipse workspace, you can check in your code to your repository workspace on the server and share your project with your team.
Check-in is the process of moving code from your Eclipse workspace 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. In the Share Project wizard, on the Share Project page, select Jazz Source Control and click Next.
  5. On the Select Component page, ensure that the chris@localhost repository connection is selected from the dropdown list at the top of the page. Also, make sure Select a component in an existing repository workspace is selected. Expand Chris on Prelude and select the Default Component. Click Next.
  6. Although you will probably not have 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.
  7. Optional: Switch to the Pending Changes view. From the Java perspective, click Window > Show View > Pending Changes. It 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 just shared. We have tracked the share operation and the corresponding changes have automatically been checked in to the repository workspace.
  8. 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.
  9. 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 just shared.
  10. 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 just created. To explore the contents of a change set, double-click on 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.
All of the changes you have made are stored in your repository workspace in the repository.

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 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 Deliver and Resolve dialog box, ensure that the Resolve work item check box is selected.
    3. In the Add a comment to the work item pane, type a comment that will be added to the work item.
    4. Click Finish.
    The work item is resolved and your code has now been delivered from your repository workspace on the server to the team 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 Team 1 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 Open Work Items. The work item is resolved and contains a link to the change set that you created for this work.

Lesson checkpoint

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

Feedback