Understanding Change sets in Rhapsody Design Manager

Content

Change sets are a concept common to the Jazz platform but understanding how they work in the context of Rhapsody and Rhapsody Design Manager can help users avoid problems when delivering, discarding or reverting them. Consider the following series of change sets in the "My DM Project Area" initial stream. The Rhapsody model in this project area and stream likely consists of hundreds of different model elements, but the five most recent change are shown below. Change set #155 contains changes to model elements you are not working on or concerned with, while the other four contain changes to the model elements you are currently working on; MyPackage1, MyClass1, MyClass2 and MyClass3.

1: Change sets are configurations that belong to a stream.

In general, the Jazz.net applications work with artifacts (Requirements, Work Items, Model Elements) and configurations (Streams, Baselines, Change sets). Artifacts are what users are concerned with and configurations are how the applications manage them; each is a collections of artifacts in a certain state or version. When Configuration Management is enabled for an application (as it always is for Design Manager), artifacts will belong to change sets, while streams and baselines are comprised of multiple change sets. Thus, when exploring a model in a given stream, whether that is through Rhapsody or the web client, what the user will see is based on the most recent version of each model element appearing in a change set in that stream. For example, if the model above was opened in Rhapsody from the initial stream, or if it was viewed through the explorer at /dm, only three of the above model elements would be visible; MyClass1 would be excluded since it was 'deleted' in it's most recent version.

2: Change sets in a stream can be thought of as being 'layered' on top of each other.

Although change sets do not store deltas (see point 4 below), the full history of any given model element is established through a series of layered change sets in the same stream. In this way, it is possible to view the history of a given element as a vertical slice. The top most version of a given element is always what will be displayed in the stream.

3: Change sets are automatically created by the Rhapsody client when you make a change to a model that is stored in Design Manager.

..unless you create a new, empty change set in the Rhapsody client first and make it the active change set. Either way, Rhapsody will be working with an active (open) change set.

When "Deliver on Save" is disabled in the Rhapsody client, each change made by the user exists only in the memory of the Rhapsody client until the user saves the model. At this time, the changes are saved to the server in an active change set. These changes are visible through the web client as a configuration that can be reviewed but they are NOT shared with the stream. Other users working with the same model in the same stream will not see these changes in their Rhapsody client. The user can 'build up' the change set over multiple Rhapsody sessions as the change set will not be locked until it has been manually delivered to the stream.

When "Deliver on Save" is enabled, there is no intermediate state. The changes either exist locally in the Rhapsody client's memory, or when the model is saved, they are delivered to the stream as a change set that will be locked and visible to other users working with that model in the same stream.

4: Change sets are automatically created by the Rhapsody client and in the web client at /dm when you create OSLC links.

Since Design Manager owns the links where a Model Element is the source or target of an OSLC link, the addition of a link - indeed, each link created - is delivered to the stream in an automatically generated change set.

5: Changes in a change set are whole copies of the version of the model elements that have been changed.

Imagine that MyClass3 (version 3) from Change set 122 contains a description that reads "The quick brown fox jumps over the lazy crocodile." This is later corrected in Change set 160 in MyClass3 (version 4) to instead read "The quick brown fox jumps over the lazy dog." Only one word of the description has changed; This class might have attributes and operations that were unchanged between versions 3 and 4, yet what is contained in Change set 160 is not simply -crocodile, +dog but rather an entire copy of the class.

6: Change sets can not be deleted once they have been delivered to a stream.

In order to maintain an accurate history of changes for individual model elements, it is not possible to delete a change set once it has been delivered to the stream, although a change set that is still active can be discarded by the user. A change set delivered to a stream CAN be reversed (see point 8 below) but this leaves the change set in question untouched and simply creates a new change set.

7: Deletion of a model element is also a change that introduces a new 'version' of the model element.

When MyClass1 (version 2) is deleted in the Rhapsody client, change set 150 is created containing a new 'version' of MyClass1. While it is flagged as deleted, it will not appear in the web client when browsing the model in this stream, nor will it appear in the Rhapsody client when the model is opened from this stream. However, it will still be possible to see the prior existence of this element in older changesets and through that, the full history of the MyClass1 element can be maintained.

8: Reversing a change set should be carefully considered!

While change sets can not be deleted once they have been delivered, whole change sets can still be reversed. This creates a new change set which effectively restores all elements to the state they were in prior to the changeset you wish to reverse. Note that individual changes can not be reversed - only the whole change set. For this reason it is important to consider dependencies - both in a modelling and hierarchical sense.

If change set 150 was reversed, it would result in a new change set containing two changes - MyClass1 (version 4) which would be a copy of the MyClass (version 2) but also MyPackage1 (version 10) which would be a copy of MyPackage1 (version 8). Changes made in MyPackage1 (version 9) will not be present and this can cause problems with the hierarchy.

Imagine that change set 155 did include a change to the model elements we are working on; the addition of a new child class to MyPackage1 called TestClass. By reversing change set 150, we create a new version of MyPackage1 that is no longer has any knowledge of the parent / child relationship to an element called TestClass.. but since TestClass exists independently of MyPackge1, it is still in the model and visible in the stream. But who does the TestClass belong to?

Resolving such conflicts can be a complicated process, and will be covered in another document.

Conclusion:

This knowledge of how change sets are used by Rational Rhapsody and Rational Rhapsody Design Manager should make it easier for users and administrators to plan their delivery strategy and review processes, and more importantly, avoid problems related to change sets and change set conflicts.