Module 3: Working with Jazz Source Control

4,725 views

Published on

Published in: Technology, Business
0 Comments
11 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,725
On SlideShare
0
From Embeds
0
Number of Embeds
13
Actions
Shares
0
Downloads
0
Comments
0
Likes
11
Embeds 0
No embeds

No notes for slide
  • 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.
  • Module 3: Working with Jazz Source Control

    1. 1. Accelerating Product and Service Innovation Course materials may not be reproduced in whole or in part without the prior written permission of IBM. 9.0 Developing Software with IBM Rational Team Concert Module 3: Working with Jazz Source Control © Copyright IBM Corporation 2008, 2014
    2. 2. Unit objectives After completing this unit, you should be able to: • Explain how source control is implemented • Define these concepts:  Repositories and workspaces  Streams and components  Change sets, change flow, and conflict resolution • Create, use, and manage these items:  Local sandboxes and repository workspaces  Change sets  Snapshots and baselines • Use the Pending Changes view to share work with your team © Copyright IBM Corporation 2008, 2013
    3. 3. Overview of Jazz Source control > Overview of Jazz source control Working with change sets Sharing changes with your team Finding and resolving conflicts Preserving and restoring component and workspace configurations Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    4. 4. Jazz source control Jazz™ Team Server  Uses a relational database in a central location for all artifacts that are based on Jazz technology: – Stores source code, documents, binary files, images, and more – Stores all IBM® Rational Team Concert™ artifacts – Supports geographically distributed teams  Provides strong support for parallel development  Supports process-centric automation, both agile and traditional processes  Provides the infrastructure to link work items, plans, source-control artifacts, and builds The Jazz source-control repository  Is entirely change-set based – Requires that all changes to artifacts are related to a change set – Ensures that atomic changes to sets of files are together  Provides secure mechanisms for creating, retrieving, updating, and deleting artifacts  Maintains a complete audit trail of all changes, including these events: – A record of past states of the item and past field values – The user who saved the item – The time of the change © Copyright IBM Corporation 2008, 2013
    5. 5. Project area hierarchy © Copyright IBM Corporation 2008, 2013
    6. 6. Components  A component is the fundamental organizational unit for artifacts that are under source control.  Components are collections of related artifacts.  For example, a component can be Eclipse plug-in or a group of documents.  Any group of files and folders that share a common root can be a component.  A baseline represents the “version” of a component. © Copyright IBM Corporation 2008, 2013
    7. 7. Streams  A stream is a collection of one or more components.  Streams are typically used as follows:  To provide a team integration area – Controlled sharing of changes sets between teams and team members  To re-create important configurations – Team integration builds – Previous releases – Stable versions of third-party or open source software packages  To provide a mechanism for a phased promotion model – Development stream or streams – Integration stream – Production stream © Copyright IBM Corporation 2008, 2013
    8. 8. Repository workspaces  A repository workspace is a server-side storage area that a developer uses for current work.  Flow target – Specifies the initial configuration of components – Identifies the location where change sets are shared  Sandbox – Provides access to files and folders for desktop integrated development environments (IDEs), such as Eclipse and Microsoft® Visual Studio®, and other development tools Repository workspace Flow target (Stream) Sandbox Jazz server Local host © Copyright IBM Corporation 2008, 2013
    9. 9. Change sets A change set is a repository object that collects a related group of changes in a component.  The system tracks the changes that you make in the context of your current work as a change set.  Change sets are applied to a flow target in a single atomic operation. The blue triangle icon ( ) indicates a change set. © Copyright IBM Corporation 2008, 2013
    10. 10. Pending changes  In the Pending Changes view, manage the flow of change sets into and out of your repository workspace.  Unresolved Files in this section were modified in the local sandbox, but have not been checked in to the repository workspace.  Outgoing Checked-in files are organized into change sets. Outgoing change sets have not been delivered from the repository workspace to the flow target.  Incoming Incoming change sets represent changes that were applied to the flow target, but that have not been accepted into this repository workspace. © Copyright IBM Corporation 2008, 2013
    11. 11. Using workspaces in a team environment Load  Copies a specified configuration of files from the stream to your repository workspace and local sandbox Check-In  Copies changed files from the local sandbox to the repository workspace Deliver  Copies the change set or sets from the repository workspace to the flow target Accept  Copies a change set or sets in the flow target into the repository workspace and the local sandbox •If the same file is modified in multiple change sets, the Deliver and Accept operations will identify potential conflicts. Load Check-in Deliver Accept Accept Load © Copyright IBM Corporation 2008, 2013
    12. 12. Challenge  Minimize the impact of emergency releases on new development efforts  Allow developers or teams to investigate solutions or new feature work in isolation  Allow large teams to stage the integration effort  Allow teams to apply fixes to multiple code releases How would you use streams and repository workspaces to support these common source-control management scenarios? © Copyright IBM Corporation 2008, 2013
    13. 13. Working with change sets  Overview of Jazz source control > Working with change sets  Sharing changes with your team  Finding and resolving conflicts  Preserving and restoring component and workspace configurations  Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    14. 14. Creating and managing change sets  Best practices:  Set your current work item.  Work on one task at a time.  If you must multitask, follow these guidelines:  Use multiple repository workspaces.  Suspend work on a change set to postpone that work temporarily. You can resume the work later.  Worst case scenario:  Before you deliver, adjust change set contents in your repository workspace. Suspend work © Copyright IBM Corporation 2008, 2013
    15. 15. Sharing changes with your team  Overview of Jazz Source Control  Working with change sets > Sharing changes with your team  Finding and resolving conflicts  Preserving and restoring component and workspace configurations  Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    16. 16. Sharing work between workspaces Multiple developers who collaborate on a task must be able to share their work: 1. Use the normal deliver-accept model to propagate a change set from one workspace to the other through a parent stream or repository workspace. 2. Change your flow target to point to the other workspace and accept changes directly from that workspace. 3. Create a patch file, which other users can apply to their workspaces. (2) Accept (3) Create patch (3) Apply patch (1) Deliver (1) Accept © Copyright IBM Corporation 2008, 2013
    17. 17. Questions In what situations would you suggest delivering to an alternative target? In what situations would you suggest using a patch and sharing it with another user? When would you insist on delivering to the team stream, and then let the changes propagate to the rest of the team with the normal deliver-accept flow of events? © Copyright IBM Corporation 2008, 2013
    18. 18. Finding and resolving conflicts  Overview of Jazz Source Control  Working with change sets  Sharing changes with your team > Finding and resolving conflicts  Preserving and restoring component and workspace configurations  Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    19. 19. Finding conflicts Conflicts are detected at the file level, so any changes to the same file by two different change sets can potentially result in a conflict.  Conflicts can be detected during either the delivery or the accept process  Rational Team Concert will offer to “auto-resolve” conflicts without user intervention.  If the changes cannot be resolved automatically, Rational Team Concert will prompt you to perform a manual merge. This might happen if the same line of code was modified in both workspaces. Conflict detected during Accept Load Check-in Deliver Accept Accept © Copyright IBM Corporation 2008, 2013
    20. 20. Resolving conflicts Use the Compare editor to manually resolve conflicts. The conflict is indicated in the Change Explorer view. Your editable version of the file. The other contributing version of the file. Conflict location indicators. © Copyright IBM Corporation 2008, 2013
    21. 21. Avoiding conflicts File locking  You can lock a file on a "per-stream" basis.  When you lock a file, only you can deliver changes to that file in that stream.  A file can be unlocked by the user who owns the lock or by a member of the JazzAdmins group © Copyright IBM Corporation 2008, 2013
    22. 22. Preserving and restoring component and workspace configurations  Overview of Jazz Source Control  Working with change sets  Sharing changes with your team  Finding and resolving conflicts > Preserving and restoring component and workspace configurations  Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    23. 23. Baselines  A baseline is a version of a component.  Component configurations can be saved at any time by creating a baseline.  Baselines are created in a repository workspace and are delivered to a stream as a special type of change set.  The Team Artifacts view indicates which component baselines are in a repository workspace or stream. © Copyright IBM Corporation 2008, 2013
    24. 24. Restoring configurations Replace the current component configuration in a stream or repository workspace with a different baseline. 3. Choose which baselines to restore. 2. Click Replace With to change baselines. 1. To edit the stream properties, open the stream object under the project folder. © Copyright IBM Corporation 2008, 2013
    25. 25. Snapshots A snapshot is a collection of baselines across all of the components in a repository workspace or stream. May 1 May 7 May 1 May 3 May 5 May 9 May 13 May 14May 14 SSMay 13 A stream contains multiple components. Each component has multiple baselines over time. A snapshot is a collection of baselines at a single point in time. © Copyright IBM Corporation 2008, 2013
    26. 26. Getting out of trouble  Overview of Jazz Source Control  Working with change sets  Sharing changes with your team  Finding and resolving conflicts  Preserving and restoring component and workspace configurations > Getting out of trouble > = Current topic © Copyright IBM Corporation 2008, 2013
    27. 27. Discarding changes Before check-in  To discard all of your local changes to a file, complete an Undo action on the file in the Pending Changes view.  To keep some of your local changes, use Eclipse local history to search for a version of the file that will work. Toggle the history display between local Eclipse history and source control version history. © Copyright IBM Corporation 2008, 2013
    28. 28. Discarding changes After check-in  To remove an entire change set, you can Suspend, Discard, or Reverse the change set from the Pending Changes view.  To discard the changes to a file, Undo file-level changes in the Pending Changes view. The rest of the change set remains. © Copyright IBM Corporation 2008, 2013
    29. 29. Discarding changes After delivery  Use the “brute force” method: Replace the component in the stream or repository workspace with a previous baseline.  If you must systematically determine which change to the stream is causing problems, use the process on the next slide. © Copyright IBM Corporation 2008, 2013
    30. 30. If the stream configuration fails to build, take these steps: 1. Accept the contents of the stream into a workspace. 2. Open the History view of the workspace. 3. Select the change sets to withdraw. Suspend each selected change set. 4. Replace the content of the stream with the content of your workspace. 5. One by one, Resume the suspended change sets in the workspace. After each change set is resumed, build it. When the build fails, you have found the problem change set. © Copyright IBM Corporation 2008, 2013
    31. 31. Other problems? © Copyright IBM Corporation 2008, 2013
    32. 32. Review How do workspaces, streams, and teams relate to each other? How do components, baselines, and snapshots relate to one another? How do developers typically share their work with the rest of their team? How can two developers share work with each other before they share it with the rest of the team? © Copyright IBM Corporation 2008, 2013
    33. 33. Unit summary Having completed this unit, you should be able to: • Explain how source control is implemented • Define these concepts:  Repositories and workspaces  Streams and components  Change sets, change flow, and conflict resolution • Create, use, and manage these items:  Local sandboxes and repository workspaces  Change sets  Snapshots and baselines • Use the Pending Changes view to share work with your team © Copyright IBM Corporation 2008, 2013
    34. 34. Exercise 3 In this exercise, you complete these tasks:  Create a workspace and begin working on a team  Associate your changes with the appropriate work item  Review and manage change sets  Detect and resolve conflicts © Copyright IBM Corporation 2008, 2013

    ×