Managing Architecture and Design Changes – A workflow for dealing with change using Rational Software Architect and Design Management
The practice of software development involves in large part the gradual evolution of a large number of artifacts ranging from process documents and requirements, to designs and test resources and to the actual deliverables. When it comes to managing design resources Rational Software Architect’s Design Management capability (RSADM) provides full lifecycle management of design sketches, UML models, business process models, topology models, design documents, as well as custom defined resources.
Change is often instigated when a newly realized requirement is identified, or when a defect is found in the current set of resources. In the modern software development process this need is governed by a process through which the change is managed, and coordinated with all the other activities in project’s lifecycle. This article will explain through a common scenario how changes to designs and the other resources related to them are managed with RSADM. We will also introduce the basic concepts of configuration and versioning enabled by RSADM 4.0. Although this article uses RSA the same Design Management capabilities are available with Rational Rhapsody as well.
Configurations
A configuration is a unique set of versions of design resources. There are two types of configurations: snapshot and workspace. A snapshot configuration is a read only version of a collection of design resources. This frozen set of versions can be relied on to act as a reference-able baseline for other configurations. While these resources are read only, they can still be commented on as comments are not considered part of a resource’s properties.
A workspace configuration is an editable set of resources. In a workspace resources can change over time (including deletion). Changes in a workspace are not visible outside of that workspace. A workspace is an area where one or more designers can make modifications to resources without disturbing other non-related work on those same resources. Snapshots are required as the base from which to create workspace configurations. To create a child workspace you must first create a snapshot in the parent workspace. Then create the new workspace as a child workspace to the one the snapshot was created in. The snapshot contains the initial versions of all the resources for the new workspace.
Workspaces use resource locking to prevent contention. As users edit resources on a workspace, resources are automatically (or manually) locked to allow multiple users to share a workspace without requiring merging. Changes to a resource are collected in a changeset. A changeset can, optionally, be referenced and associated with a change request. When a resource, in a specific workspace, is edited the changes are only visible to the user that is editing them in that changeset. Before another user can see the changes in the workspace, the changeset must be ‘shared’ with the workspace. Sharing a changeset to a workspace commits the changes to the workspace. No other modifications of the resources are permitted in the context of the changeset. They can of course be modified again, but that must be done in a new changeset, and shared again with the workspace.
There are two modes in which the changes get committed to the workspace. The first one is a ‘share on save’ mode. In this mode changes made to the resource get committed to the workspace when the user saves the resource. The other mode is explicitly using change sets which allow the user to combine multiple edits into a change set and then explicitly commit the changes to the workspace
A changeset can be ‘completed’. Completing a changeset freezes the changeset. The resource deltas cannot be altered. Explicitly completing a changeset is often done when you want to review the changes with others to get their opinion on them. The changes are made read only so that a reviewer of the changes can be assured that the changes won’t be modified again after the review has been completed. A completed changeset can be shared back into a workspace.
Changesets can be explicitly created and even named. Making changes directly to a resource in the context of workspace with the web UI, however will create an implicit changeset and automatically share it with the workspace. So if you want to accumulate multiple changes to multiple resources in the same changeset, possibly for a review, while in the web UI you must explicitly create a changeset and change your default configuration to that changeset.
After the work is done in a workspace, it is often desired to merge the changes into a common, team or integration workspace. This common workspace must be an ancestor workspace (parent, or parent’s parent, etc.). All or a subset of the changes to resources are copied into the ancestor workspace. Rational Software Architect provides a visual merge editor to help select which changes are to be copied.
Scenario
Let’s examine a common scenario. A manager notices something in a design that needs to be changed. The manager tasks one of the designers to look into it. The design is associated with a use case requirement whose alternate flow is not evident in the design. Before doing any work the designer does an impact analysis on the design to determine the scope of the change. The designer then makes the change, but before sharing it with the rest of the team asks the manager to review it. After the review the designer shares the changes with the rest of the team. In this scenario all team members are working out of a single workspace.
In this scenario we cross several integrated lifecycle applications; design, change, requirements and test management. The Rational Lifecycle Project Administration (LPA) sample application; JKE Banking: Money that Matters sample can be used to play out this scenario. This sample application can be setup with connections and sample artifacts for all four Collaborative Lifecycle Management (CLM) domains. It also defines a number of users; two of which we will use as we describe in detail how our scenario works.
Initiating and Understanding Change
In this section we will see:
- Deb, our manager, looks at a sequence diagram and identifies the need for some changes.
- She adds comments to the diagram to help explain her concerns.
- Al receives a note in his email that he has been assigned a new task
- Al follows the link to the work item.
- Al looks at the work item and follows the link in it to the sequence diagram and the requirement.
- Al creates an impact analysis diagram to better understand the potential impact of the change.
Deb views a sequence diagram describing a failed login attempt. She notices something interesting and adds a comment to the diagram.
The Links tab shows the Use Case (in RRC) that this sequence diagram derives from. Hovering over the link pops up the UI Preview (hover help) of the Use Case resource. Clicking on the link will navigate to the Use Case requirement resource of RRC.
This link to the use case resource (RRC resource) does not exist in the Money That Matters sample application. You can create this link from the links tab 
In RRC the links section shows the link back to the sequence diagram. Hovering over it will display the UI Preview of the diagram resource.
Deb decides to create a new defect to track this. From the Links tab of the diagram Deb adds a new Elaborates type of link. In the dialog box she chooses the associated change management project and the option to create a new defect.
Pressing the Create button displays the RTC resource creator dialog. Deb fills in the required fields, assigning this defect to Al the designer.
The Elaborates link, behaves like any other link from the diagram. When you hover over it displays its UI Preview.
Not long after, Al gets an email notification of a new defect assigned to him. Clicking on the link in the email he navigates his browser to the work item page.
Switching to the Links tab, Al sees the link to the diagram
Clicking on the diagram link navigates to the diagram page where he sees Deb’s comments
Al follows the link to the use case requirement, and gets a better understanding of what needs to be changed in the design. Before he makes any changes he does an impact analysis of the entire Login collaboration.
Selecting the Login collaboration model element (the container of successful and unsuccessful login scenarios), Al wants to know what components are involved in this scenario. He clicks on the Impact Analysis Diagram action icon to create an analysis diagram.
Impact analysis diagrams are dynamic diagrams that explore the relationships between resources. They are useful for understanding how a design resource is connected to other design resources or other OSLC resources like requirements and test cases.
To construct an impact analysis diagram, an Impact Analysis Configuration must be selected. This configuration defines how the diagram is to be constructed. It filters what types of resources and relationships should be displayed in the diagram. Configurations can be created by anyone with the permissions, and can be saved and used over again. Al previously created a configuration to help explore components participating in sequence diagrams.
Al uses this configuration, on the Login collaboration as the starting point to create an analysis diagram that eventually leads to the components JKE Client and JKE Server, which outside of the use case actors are the only components participating in any of the login scenarios. Impact analysis diagrams can be saved and viewed later.
Making and Verifying Change
In this section we will see:
- Al using RSA to make the changes to the diagram and model. The changes are captured in a changeset.
- Al requests Deb to review the changes before sharing them with the rest of the team.
- He creates a review of the changeset.
- Deb receives notification that she has been requested to review Al’s changeset.
- Deb navigates to the review and adds comments and completes the review.
With the impact analysis complete, Al decides to start making the changes. He uses RSA with the RTC client installed to open up the work item, and start working on it.
Al searches for the diagram name in RSA. From the searches result view he opens the diagram, with Deb’s comments in it.
Al wants Deb to review the changes before he makes them visible to everyone else. Al goes to the preference page and changes the setting in his RSA workspace to not share on save. If this option is enabled then the changes that Al makes become visible to everyone on the team when he saves the resource.
Al updates the diagram. The moment he starts editing a resource, the resource gets locked, and a changeset gets created.
Al can make his own comments or respond to other comments from within the RSA desktop application.
Al can also add new links to the diagram. Selecting the Links sub-tab in the Properties view, Al presses the New Link action. A dialog is presented, and Al selects the type of link, the project to find the resource in and type of resource. In this case Al wants to link to the Account Lockout requirement. Using the RRC resource picker, Al selects the requirement and presses OK to add the new link to the sequence diagram.
This link to the Account Lockout requirement does not exist in the Money That Matters sample application. You can create this link from the properties tab in RSA 
The new Link is visible with the other links in the Properties view.
As Al makes changes to the diagram, and the components participating in the diagram (e.g. adding a new Lockout operation on the server component), the resources get automatically locked and added to the changeset. The Design Changes view shows all the changes and locked resources associated with the changeset.
Al can rename the changeset (the default name is the date and time it was created). Al wants to give it a name because he eventually wants to include it in a review, and a user friendly name makes it easier to identify.
From the web UI, Al creates a new Review and selects the newly renamed changeset in the configuration field. He adds a description, and selects Deb to participate in it.
In RSADM, changesets are a type of configuration, just like a workspace or a snapshot. When Al saves the review RSADM notifies him that the current configuration (as shown by the configuration menu at the top of the display) is different than the selected configuration of the review.
Al clicks on the link to change the configuration, which sets the displays configuration to that of the changeset. Before Al starts the review he uses the configuration menu to Complete the changeset. Completing a changeset freezes the changes in it. This ensures to Deb that what she is reviewing will not be changed after she performs the review.
With the changeset completed, he creates a link from the review to the work item that started this entire activity so that the team can monitor the status of the review in the work item. He selects Elaborates as the link type, and the RTC project and eventually searches for the original defect to link to
The review is now linked to the defect. Viewing the defect it will show the link to the review and its status. Once the review has started, Deb sees a new review in her dashboard for the project as well as receives an email notification of the new review.
Following the review Deb sees the list of changed resources that are part of the changeset
For each resource in the review (in the configuration of the changeset) she may decide to add comments. For example she adds a reply to Al’s comment in the diagram resource.
For each resource Deb changes the status to Reviewed, and identifies if comments were added or not.
When Deb is Finished the review, Al receives a notification that the review has been completed. When he navigates to the review he sees Deb’s status for each resource. He follows the link to the one she commented on, and verifies that she is ok with the change.
Delivering Change
In this section we will see:
- Al examines the completed review
- Al finalizes the review to freeze it and verifies its status in the defect..
- Al shares the changes he made with the rest of the team
Al receives an email notification that Deb has finished her review. He navigates through the link in the email to the review page. He wants to examine the review, and see if everything is ok.
Before Al finalizes the review he verifies that the status indicates as ‘Reviewed’ in the RTC defect. Viewing the defect from RTC will show the link to the review and hovering over the link will show the UI preview of the review resource and its status.
Al now finalizes the review, and provides a brief comment.
the review finalized, Al uses the configuration menu to explore the changeset.
From the Configuration Explorer Al Shares the changeset, which makes it visible to all users in the main configuration.
Now all users will see the changes Al has made.
Summary and Next Steps
Rational Software Architect’s Design Management capability has full support for parallel development of RSA models (sketches, UML and related profiles, BMPN and Topologies). Teams can work asynchronously in isolated workspaces thereby minimizing the impact on each other. The changes can be managed and carefully merged into a main or integration configuration. Changes can be reviewed before they are made visible to the rest of the team.
RSADM 4.0 new parallel development capabilities make it possible to speed up development of designs by allowing asynchronous development and collaboration. These capabilities support very simple ‘share on save’ type collaboration, allow grouping in change sets and also provide isolation with workspaces allowing simple to complex change management.
The Design Management project on jazz.net offers a 60 day trial so you can download and try it out. The trial includes design artifacts for a sample application call Money That Matters that makes it easy to try out the features covered in this article. Additionally the library section on jazz.net contains articles, videos and other resources you may find helpful in learning more.
Copyright © 2012 IBM Corporation