Jazz Source Control – Resolving Conflicts

Build basis: Rational Team Concert 1.0
Authors: Source Control Team

Summary

Parallel development is ubiquitous in Jazz. 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, everyone has their own private repository workspace. Sometimes it will be only a couple of hours before you decide to deliver your changes; sometimes it will be a day, or longer. In addition, as outlined in Multiple Stream Development, it’s easy in Jazz to use streams for parallel development. This document is meant as a guide to how to stay friends with your team members in light of the day to day conflicts that arise.

---

Table of Content

1. Introduction
2. Awareness
3. Potential Conflicts
4. Conflict Gestures
5. Conflict Types
6. Presentation
7. Resolving Conflicts
1. Example – Bill and Markus modify the same file
   
2. Example – Bill modifies a file renamed by Markus
   
3. Example – Bill adds a file to a folder deleted by Markus
4. Example – Bill and Markus assign different file properties to the same file
5. Example – Bill auto-merges a file of unknown type
6. Example – Bill and Markus create a file with the same name (‘evil twin’)
   
7. Example – Bill and Markus create conflicting symbolic links
8. Conclusion
   

Introduction

Jazz SCM uses an optimistic locking model. Changes are made to files without needing an explicit checkout or lock. Others can also make changes to the same files in their repository workspaces.  As a result, someone will have to resolve the conflicts if and when the changes ever need to be integrated into the same stream or repository workspace. More generally though, conflicts can happen whenever a file is forked, that is two states of the file have the same common ancestor, and both states want to be accepted in a repository workspace.  Usually conflicts occur when working with other team members, but you can also create forks working by yourself in Jazz; try suspending a change set, then making other changes to the same file in another change set, and then resuming the change set.

(your repository workspace) S1 -> S3 -> S4
                                  ^
                                  |
(suspended)                 S1 -> S2       

You initially had version S1 of the file in your workspace, you made a change creating version S2 of the file, then suspended the change. You now have S1->S2 suspended. Since you suspended the change to S2, you have version S1 selected again in your workspace.  Now make another change to the file creating version S3.  You now have a change S1->S3. Resuming the suspended change causes a conflict because Jazz doesn’t know which version to select: S2 or S3? To resolve the conflict you can merge S2 and S3 and create a new state S4.  Of course, you could also choose to resolve the conflict by keeping version S3 (“mine”) or version S2 (“proposed”).  When a conflict has been resolved, it is considered merged.

For the remainder of this discussion, to better illustrate conflicts that can occur and how to resolve them, we will be using the JUnit example project.  On this project we have two developers, Markus Kent and Bill Cassavelli, who both make changes.  Markus is quick off the mark and gets his changes delivered to the stream.  When Bill accepts his changes into his workspace, he usually has to resolve the conflicts. Figure 1 shows the example project layout.

Awareness

One way of preventing conflicts is to avoid them.  Jazz provides awareness of the changes being made by other team members who are delivering to the same stream as you.  Sometimes you may want to accept the incoming changes before proceeding with your modifications and other times you may decide to wait and integrate later. It really depends on the scope and kind of changes you are making whether you should accept right away or not.

Let’s get back to our example. Bill has modified some files in his workspace. Markus has also modified some files and delivered those change sets to the stream.  Bill decides he would like to make a change to the SimpleTest class.  He notices the incoming arrow, as shown in Figure 2, meaning he has incoming changes affecting that class. 


To better understand what is happening to the file, he selects it and, using the Team > Show Pending Changes command from the context menu, shows it in the Pending Changes view (see Figure 3).  All the incoming change sets affecting the file are highlighted.  He can double-click on each change to see the actual details of the change. Bill can accept Markus’s changes before proceeding to avoid a conflict.

Potential Conflicts

For every change in your workspace that hasn’t been delivered, it is quite possible that someone else could have made a change to the same file in another repository workspace or stream. If there does exist such a fork of the file in another stream or workspace, we call this a potential conflict. For every file you are working on, Jazz doesn’t continually keep track of all its forks, instead it keeps track of the changes you are making and the changes in your current flow target. A potential conflict is a property of your workspace and current flow target. As you change your current flow target, the potential conflicts may also change.

Jazz provides awareness about potential conflicts. Potential conflicts are detected when the Pending Changes view refreshes, as shown in Figure 4. To make it easy to find changes to the same files when you select a file in the Pending Changes view it will highlight the others. You can open the compare editor to see the change for each change set.

Figure 4: Potential conflicts in the Pending Changes view

In addition, as shown in Figure 5, the package explorer shows a marker on the files which are potentially conflicted. The compare editor will not show both the conflicting changes together until there is an actual conflict. This allows you to browse the changes made that cause the potential conflict but you don’t need to resolve anything yet.

Figure 5: Potential conflicts in the Package Explorer

You cannot deliver with potential conflicts. You can either remove the change or change set from your repository workspace, or, as we’ll see in the next section, you can accept and resolve the created conflicts. To remove a change you can undo it from the change set if it is not completed (and has not been involved in previous conflicts), or you can discard or suspend the entire change set. Figure 6 shows the Pending Changes view after Bill suspends his change set that is in potential conflict with Markus’s incoming change set. The potential conflict decorations no longer show in the Pending Changes view.

Figure 6: Clearing potential conflicts by suspending

Conflict Gestures

Conflicts occur when you accept changes into a repository workspace. Whereas potential conflicts are a function of the current flow target and are not persisted, conflicts are a property of the repository workspace and live with it until they are resolved. There are currently two main UI gestures that can add conflicts to your repository workspace:

• Accepting changes
  • Conflicts can appear in the Pending Changes view when accepting from the stream you are collaborating with.
  • Conflicts can appear after accepting a change set from a work item or another workspace’s or stream’s history.
• Resuming suspended changes can also introduce a conflict.

Once you decide to accept the changes that have highlighted potential conflicts, your repository workspace will contain conflicts that have to be resolved. When accepting changes and you see potential conflicts that are unavoidable (i.e. you want to deliver that change to the flow target) you know you will need to merge. Before the conflict is introduced, there are two ways of approaching the conflict, Proactive Merging and Inverse Merging. This is really a work style preference. 

• Proactive Merging: In the first approach, you want to merge the incoming changes on top of the work you have done.  Basically you want to see clearly how the other changes will be applied to your work in the compare editor.  Nothing special has to be done, you just accept the incoming changes.  Not all of them will be applied because they are conflicted.  You merge the proposed changes on top of your work to resolve the conflicts.
• Inverse Merging: In the second approach, you want to merge your changes on top of the changes done by others.  Basically you catch up with your stream and then re-apply your changes on top.  To do this, you suspend your outgoing change set(s), accept the incoming changes, then resume your suspended change sets.  Not all of your changes will be applied because they are conflicted.  You merge the changes you made previously on top of your new current world. This approach can only be done if this is the first time you are encountering conflicts with your changes.  Once you have done some merging and resolved conflicts you can no longer suspend the change set because that would re-introduce the conflicts you previously resolved.  Instead, you will want to use the proactive merging approach.
  

Potential conflicts are less urgent than conflicts.  It’s always up to you to decide when you want to deal with potential conflicts.  Once you have conflicts, it is also your decision when and how you want to resolve them. All conflict resolution happens in the Pending Changes view. Although we may in the future show conflicts and potential conflicts in other UIs, working with conflicts happens in only one view.

Conflict Types

In Jazz, conflicts are broken into two categories: content (the contents of a file is forked) and structural.  Content conflicts happen most often.  Structural conflicts tend to occur when refactoring is taking place.  The structural conflicts that can occur are:

• Two people add the same file/folder (also known as “evil twin” conflict)
  
• One person adds (or moves) a file/folder into a folder that another person is deleting
• One person moves or modifies a file/folder that another person is deleting
• Two people move/rename the same file/folder to different locations or names.
• One person moves a file/folder to a folder where another person has already added a file/folder with the same name.

Some conflicts are easier to resolve than others.  There are auto-resolvable conflicts where Jazz is able to merge the change for you.  There are the actual conflicts that you need to decide how to merge.  Then there are incidental conflicts as well.  These are changes that can not be applied because of another conflict.  When you resolve the actual conflict, the incidental conflicts will be automatically resolved at the same time based upon how you decide to resolve the conflict. 

Presentation

Potential conflicts are shown in orange and conflicts in red.  Each conflict has a tool-tip describing the conflict and possible actions that can take place.  The icon gives an indication of whether it is a structural or content conflict.  The lightly grayed conflicts are incidental conflicts.  In Figure 7, Bill has modified AllTests.java. Markus has also modified the same file. Bill has accepted Markus’s change into his repository workspace, and now has a conflict on AllTests.java.  The tool-tip further explains the conflict and how to resolve it.

Resolving Conflicts

So now you have a conflict, what options do you have? Lots! You can undo your changes that are causing conflicts.  You can revisit your changes so that a structural conflict will no longer occur.  You can merge content.  You can move incoming files/folders to other locations in the workspace.  You can have others reverse their change sets.  You can discard change sets (yours or accepted change sets).  Apply only your changes.  Apply only the accepted changes.  It all depends on the type of conflict and how you want it resolved. The following two examples illustrate the most common types of conflicts that you are likely to encounter.

Example 1: Bill and Markus modify the same file, then Bill merges the changes with the Conflict Compare Editor

Bill has modified AllTests.java, SimpleTest.java and VectorTest.java.  Markus also modified the same files.  Bill has accepted Markus’s change set into his repository workspace and now has conflicts on AllTests.java, SimpleTest.java and VectorTest.java. The Auto Resolve Conflicts dialog prompts Bill after he accepts Markus’s changes, shown in Figure 8.


Bill usually simply clicks ‘Auto-Resolve’. This time he clicks ‘Resolve Later’ to ignore the prompt, leaving him with the unresolved conflicts in the Pending Changes view, shown in Figure 9. He knows he can also ‘Auto Resolve’ the conflicts later in the Pending Changes view.


The tool-tip on each conflict suggests using ‘Auto Resolve’. When Bill did the Auto Resolve, Markus’s changes were successfully merged in with Bill’s changes for the two files SimpleTest.java and VectorTest.java. Figure 10 shows that only AllTests.java remains conflicted.


Bill decides to manually merge the content in AllTests.java with the Conflict Editor, shown in Figure 11.


Markus uncommented the MoneyTest test suite and Bill decides to keep that change. The Conflict Editor allows him to merge in Markus’s change into his local file that contains his own change. When he is done, he saves his file (Ctrl-s) and resolves it as merged. The conflicts are cleared from the Pending Changes view and Bill can deliver his changes to the stream, shown in Figure 12.


Markus and Bill can examine any previous change or merge to any resource with the History View. Figure 13 shows the history of the changes for the resource SimpleTest.java.



The merge graph in the first column reveals that Bill and Markus modified the same initial version of the file – their version is directly linked to the initial version. The top node in the graph has two incoming edges i.e. the content of two versions were merged together. Bill’s most recent change was merged with Markus’s change.

The next example illustrates how Auto Resolve takes care of merging your content changes into a resource that has been renamed in the stream.

Example 2: Bill adds content to a file renamed by Markus, then uses Auto Resolve to merge his change into the renamed file

Bill added a test method testBoolean() to the JUnit test SimpleTest.java. Markus is refactoring the JUnit tests and renamed SimpleTest.java to ComplicatedTest.java. Figure 14 shows Bill has a potential conflict on SimpleTest.java.


Bill accepts Markus’s change set. This introduces both a content conflict (Bill added content, Markus renamed the Java class name inside the file) and a structural conflict (Markus renamed the file). In Figure 15, Bill hovers over the conflict icon to get detailed information on how to resolve the conflicts.


Bill agrees with Markus’s decision to rename the JUnit test. He wants his change (addition of a new method) to be merged with Markus’s change. He selects ‘Auto Resolve’ as suggested by the tool-tips. The conflicts go away, as shown in Figure 16. Bill’s outgoing change set now refers to the new file name.


Bill selects the outgoing change and opens a Change Compare editor. Bill verifies Auto Resolve correctly inserted his new method into Markus’s renamed test file, as shown in Figure 17.


In an Agile environment, code gets frequently refactored. Jazz resources can be renamed without losing history. This is possible because Jazz internally associates each resource to a unique ID and remembers that resource’s state, name and parent folder. Auto Resolve can deal with the common structural conflict scenarios described above.

The following examples illustrate more advanced types of conflicts that are less likely to occur.  Usually this is when extensive refactoring is going on and there are gaps in understanding who is doing what. In the next case, an entire folder is deleted while someone else has delivered changes affecting resources under the deleted folder.

Example 3: Bill deletes a folder while Markus added a file to the same folder. Bill uses ‘Move’ to relocate Markus’s change.

Bill decides it is time to remove the Money code from the project. He deletes the money package and all its content. He then notices Markus has just released a new JUnit test to the folder he just deleted, shown in Figure 18.


Bill examines Markus’s incoming change set. He decides Markus’s new test is necessary but it should really be under the samples package along with the VectorTest.java file. Bill accepts Markus’s change set and examines the structural conflict on Markus’s new test. As usual, Bill examines the conflict tool-tip to assess his options, as shown in Figure 19.


Bill decides to move Markus’s new test to the folder samples. He does this through the context menu shown in Figure 20.


The Move Conflicted Items dialog opens up. Bill can move the conflicted item to any folder in his workspace. He moves ListTest.java to the samples folder as shown in Figure 21.


Bill clicks OK in the Move Conflicted Items dialog. The conflict goes away and Bill can now see Markus’s new test ListTest.java under the samples package. He edits the Java file so its package declaration points to the new folder. Everything compiles and Bill can deliver his change set. Figure 22 shows that ListTest.java has been moved to the samples directory.


Bill picked up the most suitable solution to address this conflict. In a different situation, Bill could have decided Markus’s new test was no longer necessary after he deletes all the Money code. Bill would have used Resolve with Mine on the conflicted resource ListTest.java. ListTest.java would be deleted along with the money folder, thus resolving the conflict.

Or Bill may have realized removing the money folder wasn’t a good idea. Bill would simply discard his outgoing change set that deletes the money package and its content.

Example 4 – Bill and Markus assign different file properties to the same file

  Bill sees a new incoming file named query.xml. He accepts it and examines its file properties (Figure 23).

There are two conflicts. Markus has set the MIME Type to application/xml and Bill used the default text/plain. The Line Delimiter is CRLF (Windows) in Markus’s change and Bill sets it to Platform. Bill thinks this through and decides how to merge these changes. Markus made the right call by using application/xml for the mime type. On the other hand Bill’s choice of Platform as the line delimiter is the most practical one in this situation. Bill corrects the MIME Type to application/xml through the conflict compare editor and resolves as merged. Done! Figure 26 shows the change Bill is delivering. The resource query.xml now has the MIME Type application/xml and the Line Delimiter Platform.

Example 5 – Bill auto-merges a file of unknown type

Bill has been working on the task he enjoys the most – updating copyrights for every file. During that period Markus delivered an improved version of a script for their website. As a result Bill has a conflict on the file script.php (Figure 26).

 Bill decides to auto-resolve this conflict and – surprise – a dialog asks him to pick up the appropriate content merger for the .php extension (Figure 27).


Bill does not know much about the php file format – Markus is the expert – but he sure knows php is a text format, not binary. So Bill makes the right decision by selecting ‘Text’ Merger. Bill also wants Eclipse to remember this association so he checks the item to save this preference. The auto-resolve is now able to proceed and successfully merges Markus’s code changes with Bill’s copyrights update. Bill can now deliver his copyright changes with the resulting merge (Figure 28).


Note. Markus uses PHP plugins for Eclipse to get nice PHP script editor and debugging support (e.g. see PHPEclipse). These plugins register the php extension as a text format automatically. Bill could also have manually registered php as a text format through the Eclipse > Windows > Preferences… > General > Content types > Text > Add > php. (Figure 29).

Example 6 – Bill and Markus create a file with the same name (‘evil twin’)

Bill has completed his task ‘Add instructions to run tests’. He added a file readme.txt that describes how to run the tests in the Junit Example plugin. But an incoming change set from Markus prevents him from delivering. Figure 30 shows how Markus and Bill both created a resource with the same name and at the same location.


Bill accepts the incoming change set. The Pending Changes view shows the conflict on the resource readme.txt (Figure 31).

Example 7 – Bill and Markus create conflicting symbolic links

Since 2.0.0.2, symbolic links can be versioned on supported platforms. Bill creates and delivers a symbolic link in the JUnit Examples project to point to files in the local workspace that isn’t shared in Jazz SCM. Markus also creates a symbolic link in his workspace and sees Bill’s incoming change (Figure 36).