SCM CM and Work Item Integration

This page discusses the integration of Change Management and SCM, from change requests through the objects variously known as work items, activities, tasks, etc., to change sets in SCM, and from the change set to the version controlled resources associated with that change set. Together with other efforts not in the SCM scope, such as Requirements Management and Quality Management, these services provide traceability between requirements, change requests, code, and test, and are an essential part of the Collaborative ALM Scenarios.

NickCrossley: Of course, this entire scenario assumes that the SCM system has the concept of change sets. Are we working with any systems that do not have that concept, but have some other way of providing the traceability we want?

For an integration between change requests, work items, and change sets, we need to be able to navigate in both directions - from change request to work item to change set, and from change set to work item to change request. Note that some systems might use the same object to represent at least two of these three concepts. Note also that the knowledge of the link between a particular change request or work item and an associated change set might be stored either in the CM system, or the SCM system, or both - or even potentially in some third system. This integration therefore depends heavily on cross-system links, which is a topic being considered elsewhere. The SCM workgroup needs to be active in the definition of links.

In the absence of a clearer definition of these links, SCM services can only be defined in terms of objects and links contained within the SCM system itself. We want to be able to navigate in both directions between change sets and the files or object associated with those change sets. Requirements include:

• Finding change sets by identity
• Finding files or object versions by identity
• Finding object versions by virtue of their membership in a given baseline or configuration
• Finding the properties of a given change set, such as a change comment if there is one
• Finding the properties of a given object version, such as a change comment if there is one
• Finding the object versions associated with a change set, and their properties
• Finding the change sets associated with a given object version, and their properties
• Submitting, committing, or completing a change set
  NickCrossley Some SCM systems may not have the concept of a change set that has not yet been submitted or completed, in that the change set itself might be created by the act of submitting/committing/checking in a number of modified files.
• Displaying the content changes made with a given change set - that is, comparing the file versions associated with a change set vs. their immediate predecessors
  NickCrossley See the comments about file comparison options in the ScmBuildIntegrationStory.
• Show the change sets that were added and/or removed between two configurations; the configurations might be identified by some form of baseline, tag or label as applied during the ScmBuildIntegrationStory
  NickCrossley This report allows traceability back to the change requests that were included in a build (defects fixed), and is therefore important for integration with testing.

Examples

Synergy Example

In Rational Synergy, a change set is represented by a task. A task also corresponds roughly to an RTC work item or a ClearCase activity, so Synergy uses only two levels of object - a change request in Rational Change, and a task in Synergy, with a bidirectional link between them. Since Change and Synergy use the same repository, this link may be found and navigated in either tool. Note also that change requests can be linked to other change requests; this is often used to provide additional levels of abstraction or control where two levels are not considered sufficient.

Both the change request to task and task to object version relationships are many-to-many. A change request can be associated with multiple tasks (each task perhaps for a different release, or a different developer, or a different source repository, etc.). A task may be associated with multiple change requests (perhaps because in a redesign you fixed multiple defects), and may have many associated new or modified file versions; each file version may be associated with multiple tasks. Each task is associated with a specific release, where a release corresponds roughly to an RTC stream or ClearCase branch. To add a change to multiple branches, you associate the relevant new file versions with multiple tasks, one task for each release.

1. A task is an object in Synergy, and may be queried by name or other properties. Once found, you can get the properties of a task, including its synopsis and description, and the list of associated files (object versions). The synopsis and description form the default change comment for the associated files, but a user may also provide a specific comment for each individual file change.
2. Files are objects in Synergy and may be queried by name or other properties. One found, you can get the properties of that object version, including its change comment and list of associated tasks. If a specific comment for that file version was not provided, one would have been copied from the description of the associated task.
3. As described in the ScmBuildIntegrationStory, a configuration is represented in Synergy by a project. Projects are themselves queryable objects, and you can query for the projects that contain a specific object version, or the version of an object contained in a specific project.
4. Tasks have a lifecycle; one of the states in that lifecycle is to be assigned to a specific developer. That developer may complete the task; after checking various prerequisites, completing a task checks in all the associated modified file versions, if they have not already been checked in, and makes the task non-modifiable. That is, no additional changes may be associated with a completed task. Note that task completion may fail if the prerequisites are not met; such prerequisites are configurable by the SCM administrator, and may include such things as constraints on parallel changes, the results of static analysis tools on the modified files, etc.
5. Synergy allows you to compare any two specific versions, or any single version and its immediate predecessors - note that a single version can have more than one immediate predecessor due to merges.
6. Synergy records the tasks included in a baseline (see the ScmBuildIntegrationStory), and you can compare the tasks in two baselines, with a report showing the tasks in both baselines, the tasks only in one baseline, and the tasks only in the other baseline.
7. Because a baseline records the state of multiple projects - normally, all the parts of one product or component - a task might have been included in some of those project but not others. An example is where you decide to do a partial build late in the release cycle - you want to add a change just to one library or executable, but you do not want to risk destabilizing the product by rebuilding other parts. In such cases, Synergy can report that a task is partially included in a baseline.