Contents
Module overview 3-2
Overview of Jazz Source Control3-3
Working with change sets3-13
Sharing changes with your team3-15
Finding and resolving conflicts3-18
Preserving and restoring configurations3-22
Getting out of trouble3-26
Module summary 3-33
Exercise 33-34
Notes:
Instructor notes:
Purpose — List the unit objectives
Details —
Additional information —
Transition statement —
Instructor Notes:
Explain where you are in the course.
A few of these capabilities are broad-based capabilities that are available in all tools that are based on Jazz technology. These capabilities are provided by Jazz Foundation, which also provides collaborative capabilities.
The items that are specific to Rational Team Concert are unique to Rational Team Concert, and might not be available in all Jazz offerings.
This diagram shows how source-control objects, such as streams and repository workspaces, fit into the project hierarchy in Rational Team Concert.
The relationships that are shown here are all one-to-many relationships. One project area can have many team areas. Each team area can have several streams. Each stream can have many workspaces.
The work that a developer completes in repository workspaces is delivered to the team stream. Work that has been delivered to the team stream by other team members can be accepted from the stream into a developer’s workspace.
Streams organize the work on a project. Streams form the basis for segregating and promoting project work. As collections of different components, streams can be used to limit the scope of work and coordinate integration activities. In the establishment of repository workspaces, streams represent the shared integration area where a team collects and shares changes.
When you create a repository workspace, a flow target is identified. This target specifies the initial configuration of the repository workspace and a target where completed change sets are delivered. The flow target is usually a stream, but it might be another repository workspace.
Be sure to understand the difference between a repository workspace and a local sandbox. A sandbox is in the file system on your local computer. Repository workspaces are on the Jazz server, and you use them to securely check in versions of your work from the sandbox without having to share those changes with the rest of your team. If you are using the Rational Team Concert Eclipse client, the sandbox is your local Eclipse workspace. In the Rational Team Concert Client for Microsoft Visual Studio IDE, the sandbox is your Visual Studio workspace or sandbox. If you are using the web client or command-line tools, specify a folder on your local file system to be the sandbox. Make this folder accessible to desktop tools that you use in your development effort, such as compilers, debuggers, editors, and test tools.
Change sets are constrained to one component; they cannot include changes to multiple components.
Change sets include only changes that have been checked in.
The Rational Team Concert Information Center provides detailed information about change sets. In the information center, search for “change sets.”
Instructor Notes:
The discussion of change sets can go in numerous directions. Although only a few slides are presented, take your time and make sure that students understand change sets and change flow. Students might benefit if you talk through an example while you use a white board or highlight the change flow on this diagram.
To keep the slides from containing too much text, the student notes sections provide more information. Make sure to incorporate the information from the student notes into your discussion.
A developer's changes are checked-in from a local sandbox to a repository workspace.
Change sets are created automatically and can be associated with a work item upon check-in.
Outgoing change sets are delivered from the repository workspaces to the flow target, which is a stream or upstream repository workspace.
Incoming change sets are accepted from the flow target to individual repository workspaces.
A typical source control management workflow:
A developer creates a repository workspace and loads it from a specified stream configuration.
A local sandbox is specified as a work area. In Eclipse, this is the Eclipse workspace.
The default configuration is the “latest on the stream,” but this setting can be replaced with a defined baseline.
The developer sets the context for work by specifying a current work item.
The developer works on artifacts in the local sandbox and checks in changes to the repository workspace.
A change set is automatically created to contain the checked-in changes.
If a current work item is set, the change set is associated with the current work item. If a current work item is not set, the developer can select a work item and enter a comment about the change set. Alternatively, the developer can only provide a comment about the change set.
Note: This workflow can be an iterative process: Work, test, check-in, work, test, check-in, and so on.
When the developer is satisfied that the work item is resolved, the developer delivers the change set to the stream.
Before the delivery, the developer must accept incoming change sets.
The developer completes the required integration merges.
The developer revalidates unit tests after integration.
After all of the incoming change sets are integrated, the developer resubmits the delivery request.
The developer marks the work item as “Resolved.”
Before starting the next task, the developer resets the configuration in the repository workspace.
For new development work: To work with the “latest from the stream,” accept all incoming changes.
For maintenance work: To work from a stable baseline, replace the component in the repository workspace with a baseline version.
Instructor Notes:
Explain where you are in the course.
Best Practice: Keep your current work item accurate so that changes are added to the correct change set automatically.
If you are not diligent about working on one task at a time in your repository workspace, you might include unrelated changes in the same change set. If you or your management cares about traceability between work items and source control changes, you must resolve this situation before you deliver the change set or sets. In the Pending Changes view, you can create additional change sets as required, associate them with work items, and move file or folder-level changes between change sets in your repository workspace.
To work on unrelated tasks in the same repository workspace:
Suspend a change set to temporarily store the work that you have done so far.
Work on a second task in the same workspace. Your work will not interfere with the original work.
When the second task is completed, its change set will not have dependencies on the suspended change set. You can deliver the second change set to an upstream flow target.
Resume the original change set to accept those changes back into your workspace. If your second task modified the same files as the original change set, you might need to merge.
Instructor Notes:
Explain where you are in the course.
You can propagate changes from one workspace to another in three ways:
You can use the traditional deliver-accept model to propagate a change set from one workspace to the other though the team stream.
You can change your flow target to point to the other workspace and deliver directly from one workspace to the other.
You can create a patch file, which other users can apply to their workspaces
Deliveries to alternative targets, such as other workspaces, apply most often when two or more users are aware of each other’s work, and they know that they want to deliver all of their changes at the same time. An example of this situation is a change to a three-tier application in which a change request has three child work items: one work item for changes at each tier of the application. Users can work on their changes in isolation, keep each other up-to-date, and not deliver their changes until the work on each tier is completed.
Creating and sharing patches with other users is typically an effective way to share work with other users during path finding activities or when doing pair-programming in a geographically distributed environment.
If you have changes that can stand on their own, use the normal check-in-deliver-accept model to promote and propagate changes.
Instructor Notes:
Explain where you are in the course.
Conflicts can occur when the same resource is modified in multiple change sets. When the change sets are delivered to a common stream or workspace, a conflict is detected.
By default, Rational Team Concert does not deliver a change set if doing so results in a conflict. As a best practice, accept incoming changes to the workspace before you try to deliver outgoing changes. When you accept changes first, any potential conflicts are recognized and addressed in your workspace rather than in a parent workspace or stream where the conflict might affect team operations. After the conflict is resolved in your workspace, you can deliver the outgoing change sets.
Rational Team Concert prompts you to allow conflicting files to be automatically merged. (See the bar and controls at the top of this display.) An “auto merge” involves the analysis of the files and the determination of whether the changes impact one another. If Rational Team Concert can merge the two sets of changes, it will. If the changes are to the same lines of code or resources, you will be prompted to merge the changes manually.
You make your changes in the left window, which is your local sandbox version of the file. The right pane shows the version of the file in the contributing stream or workspace. You can scroll through the code to look at the changes in context and decide the best approach to reconcile the changes.
After you reconcile the file versions, mark the file as having been manually merged. This designation ensures that your changes do not cause future conflicts between the same two, or more, change sets.
File locking is useful for non-text files such as images, spreadsheets, and executable files. These types of files are typically difficult or impossible to merge, so you want to prevent parallel development. Locks are also useful when you are completing mission-critical updates and must ensure that your changes get into the team stream without conflicts.
When another user locks a file, you can see who locked the file in the Package Explorer view, the Repository Files view, and the Pending Changes view. You can modify the file in your repository workspace, but you cannot deliver your changes to the stream until the lock is removed.
File locking best practices
Keep files locked for as short a time as possible. Unlock the file immediately after you deliver your changes.
When you see that a file that you want to modify is locked by another user, wait to make your changes until the file is unlocked. Before you start to make your change, accept incoming change sets that contain the file. This practice helps you avoid difficult merge scenarios.
If you have an urgent need to deliver a change against a locked file, contact the lock holder or a member of the JazzAdmins group, if the lock holder is unavailable.
Transfer a lock to another user
To transfer a locked resource to another user, find the resource by clicking Search > Jazz Source Control > Locks. Right-click and then click Transfer. In the Select Users window, type the full or partial name of the user to transfer the lock to, and click Search. Select a user from the list of matching names and click Select. Click OK to transfer the lock.
Instructor Notes:
Explain where you are in the course.
To see a history of the baselines that were created for a component, right-click the component and click Show > Baselines.
Baselines are delivered to streams from workspaces and are accepted in workspaces from their parent streams.
Streams or repository workspaces can become unstable when developers deliver change sets without thoroughly integrating or testing the changes in their local workspace first. In this instance, you can easily revert to a previous stable configuration by replacing the stream contents with another component baseline.
For maintenance work on a previous release, create a stream and replace each component with the baseline that represents the release version that you are maintaining. Developers can then create repository workspaces that flow with this maintenance stream so that they can fix the previous release without disturbing current development efforts.
A snapshot is a permanent record of the contents of a repository workspace or stream.
A snapshot records the current baselines of each component. A snapshot is a repository object that you can use to return your workspace to an earlier configuration. For example, you might want to preserve the workspace configuration that was in place when you released a project for testing. A snapshot can also serve as the basis for creating a stream.
To create a snapshot:
In the Pending Changes view, right-click your repository workspace, and then click New > Snapshot.
The snapshot is numbered automatically. In the New Snapshot window, you can enter a name and description for the snapshot. If you do not want the snapshot to include all of the components in the workspace, click Advanced to edit the list of components to include in the snapshot.
Click OK to create the snapshot. The snapshot will be displayed as an Outgoing change set.
If necessary, you can deliver the snapshot to the parent workspace or stream to change its configuration.
To view the history of workspace snapshots, right-click a repository workspace or stream and then click Show > Snapshots.
Instructor Notes:
Explain where you are in the course.
To open the History view, click Window > Show View > Other > Team > History.
You can toggle between the types of history that are displayed in this view: the local Eclipse history, which shows edit times and file contents, or source control history, which shows checked-in versions and current content.
When you suspend a change set, the changes are removed from the current repository workspace. The changes are set aside and can be resumed later.
When you discard a change set, the changes are removed from the current repository workspace. The changes can be recovered by clicking Search > Change Sets.
When you reverse a change set, you undo a delivery. A special change set is created that removes the changes that the original change set made. The change set itself is not removed.
The Jazz Community website offers a tremendous amount of community-provided and developer-provided support. If you have a question and do not find the answer in the documentation on Jazz.net or the online help, you can likely find an answer in a discussion forum or in a developer blog or wiki post.
Note: Content on Jazz.net is governed by the Jazz.net Terms of Use and is provided as-is without warranties of any kind.
Instructor Notes:
Notes:
Instructor notes:
Purpose — Summarize the unit
Details —
Additional information —
Transition statement —
Instructor Notes:
Allow at least 45 minutes for this lab if your classroom is configured with a shared Jazz server or servers. During that time, students will resolve parallel development conflicts.
If students are working on stand-alone client-server systems, the lab will be much simpler. Use the extra time to discuss or demonstrate how to handle merge conflicts.
