Blogs about Jazz

Blogs > Jazz Team Blog >

Finding your changes – using releases, builds, and snapshots

It has been a busy fall and winter for the Rational Team Concert (RTC) development teams. We shipped 1.0.1 in October, followed by 1.0.1.1 in February, and we are working on 2.0. It’s probably not uncommon to have many releases on the “go” at the same time, but I must admit that it has been a bit mind bending.

On the plus side, it has really put our tools to the test. In particular, we’ve had to port changes from one development stream to the next and closely track what changes went into which releases. I’d like to walk through how we do this.

Streams, builds, and releases

First though, let’s review the Team Concert development stream structure. We have an integration stream for the current release, in our case 2.0, that we call “Weekly Jazz Integration”, and an integration stream for the maintenance release 1.0.1.X. Each component team has their own parallel stream structure to isolate their changes. Note that the stream structure in Figure 1 was created from within the Eclipse RTC client by clicking on the “Weekly Jazz Integration” stream from the Team Artifact navigator and selecting “New > Flow Diagram…” then adding the streams of interest to the flow diagram.

Figure 1: Work Item and Source Control teams flowing changes to 2.0 and 1.0.1.1

The stream structure gives teams and developers the isolation needed and the ability to integrate using a regular rhythm. When we show this instead in a time line view of the stream hierarchy, in Figure 2 below, you can see how the levels of integration allow team isolation with continuous integration. Each stream gets a build to ensure continuous health and also that each developer has their own private builds. It’s all about running continuous builds and flowing changes between different integration levels.

Figure 2: Timeline view of the stream hierarchy (Click for full-size)

The first thing of interest to most teams is to track what changes happened between two releases. Let’s take 1.0.1 (October) and 1.0.1.1 (February) and see the changes made by the Build and Dashboard teams in 1.0.1.1. There are two key practices we use to help us track exactly what we’ve shipped.

  1. We keep all the build results for milestones and releases. The build result allows easy navigation to the snapshot that was taken of the build workspace when it was built.
  2. When a build is blessed, we create a release description that is shown in the project area and links the release with the build and provides values for the “Found In” field of a work item.  We bless builds by creating a work item linked to the build with a set of approvals for each component lead.
  3. We promote the snapshots for blessed builds to the main integration stream so that we keep a common list of the blessed snapshots.

Finding what changed between 1.0.1.1 and 1.0.1

To find the changes between two releases, we start from the project area editor and open the “Releases” page, as shown in Figure 3. From here we can open the build that produced this release and open the snapshot. The snapshot is the Source Control artifact which references a list of component baselines. It’s like a read-only copy of a repository workspace. When a build is run, a snapshot is created automatically by the build engine.

Figure 3: The releases for Rational Team Concert

We start by opening the 1.0.1 build and then clicking the snapshot linked from the build result. Now that we have found the 1.0.1 snapshot, from the snapshot editor we click the “Compare with snapshot” action, as shown in Figure 4.

Figure 4: Snapshot editor for 1.0.1

Now to find the 1.0.1.1 snapshot, we simply select the “Weekly Jazz Integration” stream into which we promote all the snapshots from the blessed builds. When the comparison runs we get a summary of the changes between 1.0.1 and 1.0.1.1 grouped by component. You’ll also notice that because of the process we enforced for the maintenance stream, all change sets have an associated work item which allow traceability for each change made in the release. In this case, we can confirm that most teams focused on TVT or globalization fixes to enable Team Concert to be translated into 13 languages.

Figure 5: Change Explorer showing the snapshot comparison (Click for full-size)

An alternate way of finding if a change set in another stream is to run the “Locate Change set” action from a work item or the history view. As an example, let’s try and see where the change set for work item 68677 has flowed. First, select this change set from the history view, run “Locate Change set”, you’ll get a search dialog as shown below.

Figure 6: Locate change set dialog

In this case let’s search in the flow targets for our repository workspace and see where the change set has flowed.

Figure 7: Search results from locate change sets

This confirms that the change set has flowed to both the 1.0.1.1 and 2.0 streams.

Forward porting the changes from 1.0.1.1 into 2.0

In the last section we saw how to find the changes and see if a change has flowed to several streams. Now let’s see how to actually get changes to flow from 1.0.1.1 into 2.0. The best way to forward port changes is to use the Pending Changes view to accept the changes from the maintenance streams into the current development stream. Take the example below. It shows the Pending Changes view with the latest code from the 2.0 release, and I’ve changed the flow target to accept from the “Weekly Integration 1.0.1.X” stream for the Filesystem and AgilePlanning components.

Figure 8: Merging changes in Pending Changes

As with most feature releases, a lot of files can get modified. This is highlighted above with the orange potential conflict markers which indicate that files have been modified in both 1.0.1.1 and 2.0 and merging will be required when they are accepted. Notice that the Filesystem component has ported all the change sets from 1.0.1.1 into the current release, whereas the AgilePlanning team still has a couple left to port forward.

Note: In general you don’t want to flow baselines between development streams. Since the baselines are used to mark interesting points in time along a history, when histories are merged between two streams those points are less interesting if they are mixed. In the case of backporting or forward porting changes, focus on flowing the changes and not the baselines. There is a setting in the Pending Changes view preferences which allow hiding empty baselines.

Although there are several techniques to track work in two releases (for example, creating a work item for each release in which the fix must be made), it’s still very useful to merge the change sets into each release, even if the changes are redone differently. This allows the SCM system to be used to its potential and make it easier to track which changes still need to be ported.

When changes have to be completely re-written to be forward ported, it is still good practice to accept the change set from the previous release. When conflicts occur, resolve them using the “Resolve with Mine” action to mark the changes as merged although you won’t actually take any of the file changes. The changes are marked, and the change set is now part of the component’s history. From now on you can easily track which change sets need to be merged forward.

“Why would I have to re-write a fix? Can’t I just merge it?”. In most cases when changes between your streams are small, text merging will work fine. However, there are other cases when classes are refactored, someone fixes the bug already in another way, or too many conflicting changes exist, that it’s just easier to make the a one liner fix instead of figthing with a very busy text merge editor.

Conclusion

I have shown a lot here, so let me try to wrap up with a quick summary:

  1. The combination of Releases, Build Results, and Snapshots allows your teams to create traceability between official releases and the code you ship.
  2. Use the compare tools to compare snapshots, streams, and baselines to find out the differences between releases or at different points of time in your release cycle.
  3. Use the locate change set action to find where changes have flowed.
  4. Merge your change sets to make it easier to understand which fixes have made it into which streams.

Happy parallel development!

Jean-Michel Lemieux
Team Concert PMC
Jazz Source Control Lead