Jazz Library Configuration management: Delivering across streams in Rational Quality Manager
Author name

clm,elm,test-management,continuous-engineering-solution,rational-quality-manager

Tue, 05 Mar 2019
5 min read
0

Configuration management: Delivering across streams in Rational Quality Manager

Kathryn Fryer, IBM; Vidya Malkarnekar, IBM; Lee Thomas, IBM
Last updated: 27 February 2019
Build basis: Rational Quality Manager 6.0.6 and later, Rational solution for Collaborative Lifecycle Management 6.0.6 and Internet of Things Continuous Engineering Solution 6.0.6 and later

This article is part of a series that addresses practices and considerations for configuration management in the Rational solution for Collaborative Lifecycle Management (CLM) and Internet of Things Continuous Engineering Solution (CE). If you are not familiar with the configuration management capabilities, see version 6.0.6 of Configuration management: Concepts and capabilities and Overview of global configurations in IBM Knowledge Center.

When you enable configuration management for projects in the Rational Quality Manager (RQM) application, you can create multiple parallel configurations (streams and baselines) to support concurrent development of multiple releases or variants. This article describes considerations and recommended practices for delivering or merging changes to test artifacts across streams in the RQM application.

With configuration management enabled, RQM also supports multiple components within a project area. An artifact belongs to a single component; configurations (streams and baselines) exist at the component level. The baseline and merge operations described in this article occur within the scope of a single component. For more details on components, see the Jazz.net article CLM configuration management: Defining your component strategy.

Note:

  • These capabilities are available only in RQM projects that are enabled for configuration management. If you have enabled baselines only in your project, you have a single component and a single stream; however, you can merge changes from baselines to the single stream.
  • This article also refers to RQM as the Quality Management or QM application, and to Rational DOORS Next Generation (DNG) as the Requirements Management or RM application.

Introduction

One benefit of configuration management is the ability to reuse artifacts across multiple streams which represent different versions or variants of a product. In some cases, reuse occurs when a project team branches a new stream from another similar configuration, such as a previous release or a similar product variant. In other cases, organizations might create artifacts in one stream that they want to reuse in a parallel stream that already exists, which might require them to deliver changes across streams. In the QM application, cross-stream delivery is frequently referred to as merging changes.

There are two options for delivering changes across QM streams, as described in the IBM Knowledge Center topic Merging configurations in the QM application:

  • Merge – to merge changes to the artifacts from the target to the source stream. The user can select changes to merge, with options to resolve conflicts, and can also scope the operation to a single test plan and its associated artifacts. Merge would be the most frequent cross-stream delivery operation.
  • Restore from baseline – to replace all existing artifacts in the target stream with the versions that exist in the source baseline. Artifacts that exist only in the target stream are not modified; artifacts that had been previously deleted in the target stream, but appear in the source baseline, are restored. Like the merge operation, you can scope this to a single test plan. The user can review the changes before committing them, but must accept all or none of the changes. This option can be useful to return the stream to a known previous state, but is typically used less frequently than the more selective merge operation.

Neither of these operations deletes artifacts, with one exception: if you remove execution records or results as part of the merge operation, those artifacts and their associated results are deleted from the stream. You must manually delete other artifacts that are not needed. Note that lab management resources are not included in any merge operation because they are not versioned in the project area. Lab resources are considered to be physical instances that do not vary.  They are shared across all configurations.

This article provides guidance to help you define processes and permissions around cross-stream delivery of test artifacts as part of your configuration management adoption.

Recommended practices

The following recommendations are described in more detail in the sections that follow. They address both what you need to consider as you define your processes, and how to complete the merge operation itself.

Considerations for defining your process

Before you start work on your projects, you need to establish your usage model and define the process and related permissions for users. You will also need to educate users on the process and use cases.

Define responsibilities for merging changes and assign permissions

Decide who will be responsible for delivering or merging changes across streams, and assign appropriate permissions. There are a number of different operations and permissions related to the merge operation, including:

  • Create baseline. The source for any merge operation must be a baseline.
  • Merge changes. The operation for delivering changes from the source baseline to a target stream.
  • Restore from baseline. As described in the Introduction, this operation replaces all artifacts in the target stream with the versions in the source.

Assign the appropriate permissions for these operations at the project area level.

Users performing a merge must also have permission to update and create the different types of test artifacts.

Many organizations limit who can perform these operations for better control and governance. Responsibilities for each of these operations might fall to different individuals or roles in the organization; for example, the person merging changes across streams might or might not be the same person who creates the baseline. The Restore from baseline operation is typically less frequent than merging changes, so you might restrict permission for this operation more strictly than the merge operation.

Individuals responsible for cross-stream deliveries tend to have a broader understanding of the overall solution, so they better understand what changes to merge and how to manage conflicts. Centralizing these operations to a small group can also encourage specialization and deeper understanding of the technical details, increasing the skills of those individuals with respect to cross-stream deliveries.

You might choose to define one or more roles responsible for merge and the related operations, and assign the roles to one or more individuals in the organization. Note that the permissions apply to all configurations in the project area; currently, you can’t restrict which streams the individual or role can baseline, restore, or merge changes into.

As you define the roles and permissions, also consider who is permitted to perform other configuration-related operations, such as creating new streams and archiving configurations. These permissions also apply to all configurations in the project area.

Define the process for managing change across streams (when and why to merge)

There is no hard and fast rule on when or how often to merge; it depends on your process and your configuration strategy. Determine what is most appropriate for your organization. You might choose to merge at specific plan milestones, or when specific events occur. For some projects, merging might be an exception event as opposed to a regular operation.

Your plan for merging changes should align with your baseline strategy, which is discussed in the next section. Note that merging a large set of changes could take some time, especially if there are many conflicts to resolve manually.

Consider whether you need to record the decision to merge changes for audit or tracking purposes, for example using work items in Rational Team Concert (RTC). Each QM artifact has a version tree that describes its history and evolution; however, the system does not record the merge history at the stream level, and does not capture the rationale.

Also decide how to manage change to approved artifacts. You can configure RQM to prevent changes to artifacts that are in an approved state. If you do so, you can’t merge changes to a target artifact that is approved. Ensure your process describes how to address this scenario, for example, transitioning the artifacts in the target stream to draft state before the merge operation. If appropriate, define how to capture that decision for audit purposes.

Note: If the source artifact is approved but the target is in draft state, and you choose to accept all non-conflicting changes, the target artifact will be changed to approved state. If you do not want to modify the artifact state, manually merge the artifact to select only the content changes you want and exclude the state change.

Define your strategy for baselines

Defining a baseline strategy, including when to create a baseline, who is responsible for doing so, and the naming conventions to use, should be part of your overall adoption plan for configuration management, as described in the articles Best Practices for CLM/CE configuration management and CLM Configuration Management: Single stream strategy.

A baseline is always the source of changes for a cross-stream merge operation, as well as a mechanism to restore the artifacts in a stream to a previously baselined version.

Consider the frequency and scope of changes between baselines. If you expect to merge changes frequently, you might choose to baseline more frequently, which might also require more specific naming conventions and management of the growing number of baselines. Similarly, if you expect to merge small subsets of changes across streams (for example, for one change request out of many), you might baseline after addressing only a small number of change requests in the source, to minimize the amount of change to review as part of the merge.

Consider whether any baseline can be used to merge changes or restore a stream’s state, or if there will be officially designated baselines. This is especially important if many users have permission to create baselines, or if you define different baselines for different purposes. While RQM allows merge or restore from any baseline, you could use naming conventions to designate the baselines to use.

Take a baseline of the target stream before merging changes from the source. As you accept changes in the QM Merge wizard, the operations happen immediately; closing the Merge wizard won’t discard or revert the changes you made. If the merge results are not what you intended, you can use the baseline you just created to revert the artifacts to their previous versions. See the section If your merge operation does not yield desired results for more details.

Exclude execution records and results from merge (in most cases)

Most organizations do not merge execution records and test results across streams; each stream represents a separate release or product variant, tracking its own execution and results. If this is true for your organization, set the Project Properties to exclude execution records and results from the merge operation to avoid someone merging them inadvertently, as shown below. You can also choose to exclude these artifact types when cloning or creating new streams.

There are possible scenarios for merging execution records and results across configurations, for example, where a branched stream represents a lower level of development within a system and you want to include its test results in a higher-level stream. (Note that this could be a very complex usage scenario, with implications beyond those related to the merge operation discussed here.) There might be other scenarios related to exceptional circumstances. If you choose to enable merging for execution records and results, the merge operation works the same as for the other test artifacts; however, you should note:

  • When you merge an execution record or result, the operation also includes any associated test artifacts (for example, test case, suite, plan) that don’t already exist in the target configuration. If the associated test artifacts do exist, the merge updates them to reference the execution record and/or result; however, you need to explicitly merge those associated artifacts to include any other changes to their content. See also the sections below on scoping for reuse and understanding artifact dependencies.
  • Conversely, merging a test plan or test case does not automatically merge or add the associated execution records or results. The user must explicitly merge those additional artifacts.
  • If you remove execution records or results as part of the merge operation, those records are deleted from the target configuration. (Execution records and results are only meaningful in the context of the test plan.)
  • In a configuration, you can have only ONE execution record for the combination of test plan, test suite (if used), test case, iteration, and environment. If you create an execution record with the same combination in a second stream, even if that execution record has a different ID, you cannot merge that record across those streams. This scenario that should not typically occur.
  • To merge test results, use the merge wizard. You can’t merge test results from the Versions graph of another test artifact.

Scope test artifacts to facilitate reuse

Consider how test artifacts will be common or vary across streams, and what change is likely to flow across streams. Establish test plans and their content accordingly to make it easier to deliver changes across streams.

There are several behaviors or capabilities related to merge to consider as you organize your test artifacts:

  • You can scope merge and restore operations by test plan. You might choose to maintain separate test plans for artifacts that are more likely to require cross-stream delivery.
  • Merging some types of artifacts will also merge their referenced or dependent artifacts, as described in this Knowledge Center topic and the section on artifact dependencies below. For example, if you merge a test plan that includes test cases that don’t exist in the target stream, those test cases will be created in the target stream. If you merge a test result from a test plan that does not exist in the target, the test plan and all of its test cases will also be created in the target. Organize your test artifacts to ensure merge operations do not inadvertently include unwanted artifacts.

Considerations for performing a merge operation

As described in the IBM Knowledge Center topic Comparing and merging test artifacts, the QM merge operation uses the same user interface as the operation to compare artifacts between configurations. The following practices relate to the merge operation itself.

Baseline the target stream before you merge changes into it

Before you start the merge operation, take a baseline of the target stream. As described in the section on baseline strategy, when you accept changes in the Merge wizard, the operations happen immediately; closing the Merge wizard won’t discard or revert the changes you accepted.

If the merge results are not what you intended or wanted, you can use the baseline to revert the artifacts to the versions from just prior to the merge or even to branch a new stream that matches the pre-merge stream. Then you can try again to merge changes from the original source baseline into the target, if appropriate. For more details, see the section on what to do if results aren’t what you wanted.

Use the merge wizard to merge changes

For most cross-stream deliveries, you’ll use the merge wizard by selecting Merge Configurations from the configuration context menu. Always start the merge from the target stream, pulling the changes from the source baseline. If you need to merge only a small number of artifacts, you could alternatively merge using the Versions graph for those artifacts, as described in a later section.

The user interface for merging or restoring is very similar to the one for comparing across configurations; it identifies the number of artifacts of each type that differ, lists the specific artifacts when you select the artifact type, and can show side-by-side views for individual artifacts highlighting the differences. You can also start the merge operation from a configuration comparison.

You can scope the merge or restore operation to a single test plan and its associated artifacts to reduce the number of changes to consider and make the delivery more manageable. Depending on how you’ve organized your test artifacts, you might need to repeat the operation for multiple test plans. Note that if you always scope by test plan, you won’t see artifacts that don’t belong to any test plan.

To start merging, you select an artifact type from the list of those with changes. As mentioned previously, if you are restoring from a baseline, you can explore and review the changes to be delivered (whether for a single test plan or the entire configuration), but then you must commit all the changes, or close the wizard and make no changes at all. With the merge operation, you can select which changes to accept, even down to the level of the sections in an artifact.

As you select each artifact type from the list, the wizard shows you the list of changed artifacts for that type. You can choose to:

  • Merge all non-conflicting changes for all listed artifacts of that type (for example, all test cases) by selecting the merge icon. The merge operation happens immediately.

  • Merge or exclude all non-conflicting changes for one or more selected artifacts from the list. Select one or more artifacts from the list and use the action menu to accept or exclude the changes. The merge operation happens immediately.

  • Manually merge selected changes for a specific artifact, addressing any conflict changes, by selecting the artifact and choosing Manually Merge from the action menu (processing one artifact at a time). From a side-by-side comparison view (the same view used to merge an artifact from its Versions graph), you can:
    • Accept all non-conflicting changes (icon marked A in the screen capture below)
    • Merge or exclude individual sections (icons marked B)
    • Merge one or more associated artifacts, for example test cases in a test plan (controls marked C)
    • Edit specific fields or attributes in the target artifact to resolve conflicts.
    You must click Save and Close for the merge to take effect; you can exit this view without making changes by clicking the x in the top right corner.

As you merge artifacts, the wizard updates to show you how many artifacts you’ve merged and how many remain. You do not have to merge all the artifacts before you close the wizard.

For more details on the steps for merging changes, see the IBM Knowledge Center topic Compare and merge operations for test artifacts.

It’s important that the person performing the merge operation understands what changes are to be merged, which is why it’s important to assign the permissions for the operation to individuals in your organization with appropriate skills and visibility across your product configurations. It’s also important to understand how artifact dependencies or references can affect the merge operation, as described in the later section on artifact dependencies.

Merge individual artifacts from their Version graph where appropriate

Most cross-stream deliveries are likely to be for a broad set of artifacts, or even the entire configuration, using the merge wizard. However, there might be scenarios where only a small number of artifacts are changing or need to be restored to a previous version. In those cases, you could choose to merge changes for individual artifact using the Versions graph.

Test artifacts include a graphical Versions view that illustrates the evolution and versions of the artifact across different streams and baselines.

From the graph, you can select and compare two versions of the artifact from different configurations. You can also choose a version from any existing baseline to merge into the current version. Like any merge operation, you start the operation from the target, and the source must be a version from a baseline. The compare and merge operations invoke a view similar to what you see in the Merge wizard when you manually merge an artifact. Like the manual merge, you can merge the entire artifact, specific sections, or specific changes. You must click Save and Close to accept the changes and complete the merge operation; to exit without making changes, click the x in the top right corner.

If you are merging only a small number of artifacts or distributing that responsibility across a team, you might use the Versions graph to merge the artifacts individually. Alternatively, you might use the Versions graph to individually merge a small number of artifacts that require more manual intervention before invoking a broader merge at the configuration level, to avoid having to search for those artifacts in a larger number of changes.

Using the Versions graph works only for artifacts that already exist in the target stream. If you are delivering new artifacts across streams or modifying artifact relationships (for example, adding test cases or execution records to a test plan), use the merge wizard to ensure you have merged all the necessary artifacts. If you want to merge test results, you must use the merge wizard.

Understand how dependencies affect the merge operation

When you merge an artifact between configurations, it might also merge referenced or dependent artifacts that don’t already exist in the target configuration; for example, if you merge an entire test plan from a baseline that includes test cases, suites, or scripts that don’t exist in the target stream, the merge will create those additional test artifacts in the target stream. At the same time, merging one artifact does not necessarily merge all changes to its existing dependent artifacts; if the test plan has the same test cases in both streams, but those test cases vary in content, merging the changes to the test plan does not merge all the changes to the individual test cases.

The individual performing the merge needs to understand the dependencies, and also what changes are appropriate to be merged. In some cases, you might merge the entire artifact or the set of dependent artifacts; in others, you might selectively merge only some of the artifacts or specific sections.

The IBM Knowledge Center topic Referenced artifacts describes the artifact dependencies as they pertain to cloning; the same dependencies apply when you merge artifacts with dependencies that don’t exist in the target stream.

If your merge operation does not yield desired results

As noted previously, when you accept changes in the merge operation, those changes happen in the target stream immediately. Closing or exiting the merge wizard does not discard changes you have already accepted.

If you accepted changes you do not want, and you have an existing baseline for the target stream that you took before the merge operation (as described in an earlier section as a best practice), you have several alternatives to recover the artifacts to the desired versions:

  • Restore from the baseline. Chose this option to restore the entire configuration, or an entire test plan and its associated artifacts, to the versions from before the merge operation. You must accept all or none of the changes. Restore from baseline does not delete new artifacts added during the merge, with the exception of test execution records and results that are removed from test plans. If the merge added other new artifacts, you would need to delete those manually.
  • Merge using the pre-merge baseline as the source. Choose this option to restore only selected artifacts or artifact sections from the baseline. For a very small set of artifacts, you could also use the artifacts’ Version graphs to merge them with the pre-merge baseline. The merge operation will not delete artifacts added in the original merge, with the exception of test execution records and results that are removed from test plans.
  • Branch a new stream from the baseline. This option gives you a stream exactly like the one you had prior to the merge. If you plan to continue using this stream, you will need to update your global configurations accordingly.

Once you have restored or branched your target stream, you can try again to merge changes from the original source baseline into the target.

QM test artifacts can use OSLC link types to link to requirements, work items, and architectural design (model) elements in the other CLM/CE applications. With configuration management enabled, these links resolve based on the user’s current global configuration context. Delivering changes across streams, which could contribute to different global configurations, can affect link visibility and resolution. The behavior varies depending on whether you are linking tests to versioned artifacts (such as requirements or model elements) or linking to work items which are not versioned. If your organization uses change sets for requirements in Rational DOORS Next Generation (DNG), you should also be aware of considerations for linking to or from those RM change sets.

Note: You must be in a global configuration context to view and resolve cross-application links. If you set your context to a local configuration, cross-application links will not resolve correctly or might not appear at all.

For links to versioned artifacts like requirements or model elements, RQM stores the link information and publishes it to the link index service (LDX) for the target application to discover. The link is between the specific “concept” artifacts based on the artifact ID, but the versions of each artifact are determined based on the current global configuration (GC).

When you merge that linked test artifact into a different QM stream, the behavior of the links to requirements and models depends on the target QM stream and the global configuration(s) that target stream contributes to, as illustrated by the following scenarios. (The examples show linking to a requirement, but also apply to links from QM artifacts to model elements.)

  • If the target stream contributes to a global configuration that includes a version of the requirement, the QM artifact link will resolve to the appropriate version in that new global configuration context. DNG discovers the incoming links from LDX and displays them with the requirement.

    The same link can exist and resolve in multiple configuration contexts, depending on where the artifact versions exist and how they contribute to different global configurations.

    Link validity persists between specific versions across configurations, meaning if the link was deemed valid in the source context, and the requirement or model element in the target global configuration context is the same version as that in the source, the link from the test artifact will still be valid in the new global configuration context. If the requirement or model element in the target global configuration has a different version, the link from the test artifact will be set to suspect. For more details on link validity, see Using link validity in CLM applications in the IBM Knowledge Center.

  • If the requirement does not exist in the global configuration where the target stream contributes, the link from the test artifact will be broken and unresolved.

    If you later added the requirement artifact to that global configuration (by delivering from another RM stream), the links would then resolve correctly in the QM artifact and display in the requirement artifact.

  • Conversely, if someone delivers requirement changes to an RM stream in a different global configuration, and the version of the QM test artifact in that global configuration does not have a link to the requirement (or the QM artifact doesn’t exist in that configuration), the requirement does not display any incoming link.

    DNG will not discover an incoming link in the context of that second global configuration.

  • If the target QM stream does not contribute to any global configuration, the test artifact displays unresolved links to requirements or models because those links resolve only in the context of a global configuration.

Link resolution in the original configuration context is not affected by the cross-stream delivery.

Note: You can also link a QM artifact to a source file in RTC, which is versioned in RTC source code management (SCM). In that scenario, RTC stores the link and publishes it to LDX. Link resolution is consistent with the description above, with the RTC configuration acting as the link source (instead of RQM), and the QM configuration as the target (instead of RM or DNG).

Linking behavior between versioned artifacts (like QM test artifacts) and work items differs from the behavior described above for linking between two versioned artifacts. Work items are not versioned, and are not part of a configuration, so they do not explicitly contribute to a global configuration. Instead, user-defined settings and associations in RTC between link types, work item attributes, releases, and global configurations indicate the configuration context for a work item, as described in more detail in the Jazz.net article Configuring Rational Team Concert to establish a global configuration context for work item links.

RTC stores the link information related to work items, and RQM discovers the incoming links from LDX, the link indexing helper application. These links still resolve only in the context of the current global configuration. However, unlike requirement links, links to work items resolve in only one single global configuration context at any time, based on the work item attribute values and the associations defined in RTC.

When you deliver across QM streams, if the work item link is set to resolve in the global configuration context that includes the source configuration, it will not resolve in the global configuration context for the target configuration after you merge, and it will not appear in the QM artifact. If you change the RTC settings or values so the link appears in the global configuration context for the target configuration, it will no longer resolve in the original global configuration context or appear in the QM artifact in the original source configuration. This behavior is described in more detail in Configuring Rational Team Concert to establish a global configuration context for work item links.

Carefully consider how to configure RTC for the linking behavior you want. In some cases, you might choose to create duplicate work items, for example so you can track a defect against two different configurations. For tasks, you might simply ensure that the work item is linked to the correct configuration where the work is to be done. You might also choose to use RTC queries for some tracking and reports, rather than relying only on the traceability from the test artifacts in a single configuration. Details will depend on your process and needs.

One other special use case to understand is linking with RM change sets in DNG. Although this use case is not strictly related to merging across QM streams, it can cause confusion and might impact your process definition.

When an RM user creates a change set in the context of a global configuration, their context changes to a personal stream, which includes the change set as well as the other contributions of the global configuration itself. Personal streams are described in more detail in this blog post.

In that personal stream, the user can create links between the requirements in the RM change set to existing or new QM test artifacts in whatever QM stream contributes to the global configuration underpinning that personal stream. Changes to the requirements in the change set can be discarded; they are only committed to the parent RM stream when the user delivers the change set. However, changes to the QM artifacts to add links or new artifacts happen directly in the QM stream. If the user discards the RM change set, the changes and links persist in the QM test artifacts. If the requirement artifact already existed in the RM stream where the change set was created, the link from the test artifact resolves to the requirement in that stream; if the RM artifact does not exist in that parent stream (meaning it was created and then discarded in the change set), the link in RQM will be broken. Users must manually remove or change those links or artifacts.

Because of this behavior, it is a good practice to create links from your test artifacts to the requirements once those requirements are in a more mature state, ideally to a requirements baseline or at least to a stream. Users who work in global configurations that include streams for both requirements and test artifacts must be careful when working in personal streams.

Summary

Enabling configurations provides flexibility to reuse test artifacts across streams, and to merge changes across streams where appropriate. It is important to understand the behavior and mechanics of the merge operation as you plan your configuration management adoption and processes to ensure that it addresses your organization’s needs.

For more information

About the authors

Kathryn Fryer is a Solution Architect with over 25 years at IBM, most recently focused on the IBM CE/CLM solutions including global configuration management. She works closely with customers, sales, and development to develop usage models, aid adoption, and improve product offerings. She can be contacted at fryerk@ca.ibm.com.

Vidya Malkarnekar is an Advisory Software Engineer  with over 15 years at IBM. She is a part of the CLM Support Team with focus on RQM. She can be contacted at vmmalkar@us.ibm.com.

Lee Thomas is a Senior Managing Consultant for IBM Watson IoT Lab Services.  With over 35 years of experience, he is a subject matter expert in all aspects of testing. He has helped clients to advance the state of their testing practices in industries as varied as telecomm, network appliances, automotive, aerospace, medical devices, insurance, and retail.  Lee is a recognized leader in testing of real-time systems and in test management, as well as test automation. As a Cognitive Engineer and thought leader, Lee applies artificial intelligence to problems and opportunities in the Software and System Development space.

© Copyright IBM Corporation 2019

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Tue, 05 Mar 2019