CLM configuration management: Multistream variant strategy
Todd Dunnavant, Ph.D., P.E., IBM
Last updated: 13 November 2017
Build basis: IBM Collaborative Lifecycle Management Solution (CLM) 6.0.4 or later, IBM IoT Continuous Engineering (CE) Solution 6.0.4 or later
This article is part of a series that provides guidance for planning configuration management for the IoT CE solution.
This article discusses patterns of stream usage for situations where multiple variants of lifecycle artifacts need to be maintained in parallel for each of several releases. This is a common need of product-centric organizations.
These and other patterns – including several that these patterns build on – are introduced in the companion Patterns for stream usage article. Read about these base patterns before you read this article. You’ll also find links there to the other stream pattern articles in this series.
The patterns we present here are the most complex stream usage patterns. If an opportunity to “go simpler” presents itself, even for a single component, we encourage you to do so. For example, if you can build and maintain a reusable component of regulatory requirements using a single-stream pattern, rather than using one of the multistream patterns, by all means use the simpler pattern.
This article starts off with a simple example to help you understand what we mean by variants. It explains the structure and applicability of two stream patterns, with examples of local configurations:
- Sequential releases with multiple variants per release
- Multiple variants with parallel releases per variant
Because structure and creation concerns for variant global configurations are largely independent of the stream pattern used for local configurations, this article addresses the characteristics of variant global configurations after discussing the two stream patterns above.
You’ll also find three approaches for creating the global configuration hierarchy for a variant:
- Fortuitous reuse: solution engineers start their global configurations from the work performed by other solution teams.
- The Application Engineering pattern: solution engineers leverage available common artifacts (“platforms”) to jump-start their work.
- The Domain Engineering pattern: available assets are a superset of what is needed to compose any solution. When using this pattern, the solution engineers remove or filter out extraneous content in order to define their solution.
Characteristics of variant-based development
In multivariant development, multiple product lines – or several variants of a single product line that are created from a common base – can have these characteristics:
- They co-exist: the products or product variants are being developed and maintained at the same time.
- They share a common base set of lifecycle artifacts, such as requirements, verification and validation artifacts, design elements, and physical, software, or firmware components.
- Each variant has at least one unique characteristic.
Consider different instances of a fictional “Model Year 2030 Superbrand Cool Car” automobile, which could have three variants for options:
- One variant has an ejection seat for the front passenger and a quick-opening moon roof in the passenger’s side of the automobile’s roof to accommodate the use of the ejection seat.
- Another variant includes a full-immersion, virtual-reality-based infotainment system, for which the most economical wiring layout conflicts with the placement of the components needed to support the ejection seat option.
- A third variant includes both the ejection seat plus moon roof and the VR-based infotainment system, with changes to the vehicle to support (at an added price) the requirements of each of the normally-incompatible option packages.
Most of the base lifecycle artifacts for any vehicle instance are shared among the three variants. However, the creation of each variant results in either (1) creating new, unique artifacts or (2) tailoring initially-common artifacts. The tailored artifacts no longer can be widely reused by other variants.
Sequential releases with multiple variants per release – local configuration concerns
This pattern includes characteristics of both the single stream pattern and the multistream concurrent release development patterns.
- Work on each variant occurs in a single stream, with baselines taken for this variant along this stream.
- Each variant stream can be initiated either from a baseline of the “main” stream for the product line or from a baseline of another variant stream.
The changes for any variant might be:
- Unique to that variant and not shareable with any other stream
- Shareable with select variant streams
- Appropriate for adding back into the main stream
The following diagram illustrates the characteristics of a representative configuration tree for this pattern, based on the Model 2030 Superbrand Cool Car.
Notice these elements in the diagram:
- Both the Ejection Seat and the VR Infotainment System variants branch from a body of common artifacts.
- During the work for Release 1, some widely shareable changes were shared from the Ejection Seat variant back to the main branch. These changes were then shared with the VR System variant.
- The decision was made to start the Ejection Seat + VR System (ES + VS) variant by branching from the Ejection Seat variant. To complete the initial set of artifacts for the variant, pertinent content was shared from the VR System variant.
- During the completion period for the second product line release, unique changes from the ES and VS variants were shared with the ES + VS variant.
- Finally, some bug fixes were shared from the VR System variant to the ES + VS variant.
Because there is no set pattern of deliveries between streams, it is very important that you plan inter-stream deliveries carefully and use a governed process.
Naming conventions for local configurations
As time goes on, the configuration tree (the network of streams and baselines) for local components will become more and more complex. We strongly recommend that, as part of your governed configuration management process, you define and follow a naming convention so your team members quickly and consistently understand the key characteristics of a given configuration.
Local baseline strategy
Ensure that baselines for each of the variants conform to the guidance in the single stream strategy article. Further, we recommend that you take variant baselines before doing any cross-stream delivery to the variant stream.
Multiple variants with parallel release streams per variant – local configuration concerns
This pattern combines the characteristics of the previous multivariant pattern and one or more of the multistream concurrent release development patterns. This pattern is commonly used for product-centric development when several teams are progressing different aspects of a variant at the same time. For example, a development team could use a “release” stream to develop their feature before delivering their work back to the main variant stream.
The next diagram shows some of the aspects of this pattern. Here, this diagram adds a tree of parallel release streams onto the Ejection Seat + VR System variant stream of the previous stream diagram. In this case, the parallel streams are created and managed using the “Branch from Product Main Branch” pattern for multistream concurrent release development. The “Branch from previous release” pattern also could have been used here.
To simplify the diagram, we’ve removed some of the icons that represent the baselines you should take of a target stream before each cross-stream delivery to it. Remember, you should still take these baselines.
You can see where the ES + VS variant team adopted the “Branch from Product Main branch” pattern for managing multiple release streams. This pattern has the following characteristics:
- All release streams are branched from a main stream. This branching reduces the depth of the stream hierarchy and enables archiving of streams associated with older releases.
- All sharing with the main stream is done from the newest release stream. As shown, in two instances changes were shared from the Release 2 stream to the Release 3 stream, and from there, back to the main stream.
- Changes are shared in a stair-step manner from older to newer streams. For example, in two cases changes to the main stream were shared with the Release 2 stream; then, the changes were shared from the Release 2 stream to the Release 3 stream.
Just as in the sequential release with multiple variants per release pattern, changes that are created for any variant might be:
- Unique to that variant and not shareable with any other stream
- Shareable with select variant streams
- Appropriate for adding back into the main stream of the component
Further, cross-variant deliveries of change are not necessarily limited to flows between the main streams of the variants. Theoretically, changes can be delivered from the Release X stream of Variant A to the Release Y stream of Variant K.Clearly, this pattern has many potential cross-stream delivery paths. Therefore, you must carefully plan and govern cross-stream deliveries. It’s best if you do define standard delivery patterns. For example, you could define the a rule that states the following:
- All cross-variant deliveries are to be delivered between the main variant branches.
- Deliveries between Main and Release branches of a variant follow the rules of the multistream concurrent release development pattern you have adopted.
Global configuration characteristics for variants
In any large development effort, a global configuration (GC) for a product variant is almost always a hierarchy of global configurations. This hierarchy might be constructed as a top-level GC to organize contributions from all solution component teams, plus a hierarchy of associated GCs, each of which exposes the lifecycle artifacts managed by the pertinent component team. The following diagram illustrates this concept, presenting a portion of the GC hierarchy for one variant of IBM’s Automated Meter Reader (AMR) sample artifact set. The abbreviations indicate where the local stream or baseline comes from:
- RM = Requirements Management – local configuration managed by DOORS Next Generation
- DM = Design Management – local configuration managed by Rational Design Manager
- QM = Quality Management – local configuration managed by Rational Quality Manager
- CCM = Change and Configuration Management – code stream managed by Rational Team Concert (RTC) source control management (SCM)
Here, you can see that all the solution-level configurations are streams (work in progress), either global or local. The Meter Reader Component stream includes an MR Reqts stream, with a mix of local baselines and streams. Evidently, some teams have finished their work and baselined their contributions. The Meter Interface Component global configuration is a baseline, and contains only other baselines in its configuration hierarchy.
This GC hierarchy will change as the team creates variants:
- The team is likely to add and subtract nested configurations for different GC hierarchies, according to the needs of the variant. For example, an EU variant of the AMR hierarchy shown above might replace the AMR Solution Reqts GC with a Europe-specific AMR Solution Reqts (EU) GC. This variant GC might replace the “Stakeholder Reqts” and “System Reqts” local streams in the original GC with “Stakeholder Reqts (EU)” and “System Reqts (EU)” local streams.
- The team will probably reuse a given nested configuration across multiple GC hierarchies. For example, the “MI Design” and “MI Validation” baseline configurations of the “Meter Interface Component [handheld US]” might be included in many variants.
Discriminating between GCs using naming conventions and tags
The “production scale” GC hierarchy for any product variant is likely to contain numerous lower-level GCs. Further, over its lifecycle, the GC hierarchy for any product variant is likely to have many different configurations based on product release streams and overall product variant baselines.
To manage the complexity that can occur with a long-lived, multivariant product, we recommend that you use a two-fold approach: meaningful naming conventions for your GCs, and tags for your components and GCs. For example, you might use a special tag for each variant. See the component organization section of the Defining your component strategy article for guidance on using tags. This advice also applies to global streams and global baselines.
Creating a new variant
Variant teams will most likely prefer to not create an empty GC and then build out the total hierarchy manually. Doing so can entail substantial effort for a variant GC with tens to hundreds of contributing global configurations and even more contributing local configurations. We’ve seen clients use three main patterns. The first approach, fortuitous reuse, is most commonly used in organizations that don’t invest in intentional reuse. The other two are suitable for organizations that make concerted efforts to create and maintain reusable assets.
Pattern 1: Fortuitous reuse
Use this approach if no product-line organization is responsible for maintaining standard lifecycle artifacts. You can also use it if the new variant differs relatively slightly from an existing variant. Here, the variant team does the following tasks:
- Select the existing product-line variant GC that the team believes best models their variant.
- Baseline this variant, so that there is a clear starting point for the solution team.
- Branch the new variant GC from this baseline.
At this point, the solution team has an initial GC tree. However, substantial work is needed to provide them with their “best” starting point. The team continues with the following tasks:
- Work with the owners of their solution components to identity each solution component GC that best meets the needs of the variant.
- Replace each of the GCs in the variant’s initial GC tree with the appropriate solution component GC.
- Add other configurations that are needed by their variant.
- Remove unneeded configurations.
- Modify the GC tags and other custom attributes to reflect the new variant rather than the old one.
Many clients begin with the fortuitous reuse approach, because they don’t have standard lifecycle artifacts they can leverage to save time and improve quality. These clients face the following issues:
- Excessive variability in the quality of solution starting points
- Substantial effort needed to identify the most appropriate starting point
- Proliferation of variability in general
- Excessive effort to propagate change through a product line (such as a defect fix)
Pattern 2: Application engineering
To understand this approach, consider that many software applications are created by starting with one or more standard software frameworks and then adding application-specific code. The Application Engineering pattern for jump-starting a variant GC philosophically is similar. To use this pattern, an organization intentionally creates, maintains, and reuses standard lifecycle assets. They use these assets to define, implement, verify, and validate large, reusable solution frameworks and discrete reusable solution components, depending on their situation.
They commonly provide these assets as global baselines – single global baselines for atomic solution components, or hierarchical global baselines for either complex solution components or solution frameworks.
Teams involved in the pattern include:
- The team and sub-teams that are responsible for delivering a capability (up to and including an entire system) to end users. Here, this is called the solution team.
- The teams that are responsible for creating and maintaining the reusable components that are leveraged by the solution team. Here, these are called reuse teams.
They follow a procedure like this to create the variant GC tree:
- The solution team works with the reuse teams to identify the correct reusable assets for initiating their project.
- In some cases, the solution team starts with a provided asset. Portions of the baselined asset are replaced with editable streams that are derived from the original baselines.
- The solution team adds the reused GCs to create the initial hierarchical structure of their variant’s GC tree.
- The team adds other configurations that are required by their solution.
- The team removes configurations they don’t need. The reused assets might contain content they don’t need for the current solution.
As the solution progresses toward completion, it is possible that the solution team will either (1) discover issues with the reused content, or (2) discover useful additions to the reused content. In either case, they will want to point this out to the reuse team. For issues, the reuse team can implement a fix that can be delivered to the solution team. For additions, the reuse team can accept changes from the solution team into their core reusable content.
Pattern 3: Domain engineering
This approach is intended to provide reusable content as a “150% solution” for any variant. That is, the solution team begins with content that exceeds their needs, and through one approach or another, they filter the content down to just what they need.
- In some cases, the reuse library has extra GCs or local configurations that can be removed from the solution.
- In other cases, the extra content might reside in a local stream that is needed by the solution. In this case, the solution team must use other approaches, such as using filtered views or removing artifacts from DOORS Next Generation modules, to “hide” the unnecessary items.
Note that deleting artifacts from streams is discouraged, because this can cause problems with future cross-stream deliveries.
It is almost inevitable that a solution team will eventually discover that they need some content that is not in their reuse library. Various IBM clients address this situation in different ways. In some cases, the reuse team is responsible for creating the needed content and delivering those changes to the solution team. Other organizations permit the solution teams to create their needed content, which is then back-ported to the reuse library by the reuse team.
This pattern is not necessarily straightforward to implement. It can be difficult to define all the solution variation points. After they are defined, the reuse team then needs to implement approaches for filtering content based upon the variation points.
- A common technique is using attributes for this filtering, but this approach doesn’t always scale well. For example, if there are 1000 variation points that define a solution, each lifecycle artifact might need 1000 filter attributes, each with its list of selectable values. Maintaining this array of attributes and selections can be a daunting task. This approach can be automated to some degree by using the IBM tool APIs to create purpose-built automations. Talk to your IBM team for more information about this automation approach.
- Another approach is to use feature-based variant management solution from IBM partners, which work with the IBM tools to automatically select and configure the common assets to use with a given variant. Talk to your IBM team for advice and current information about these partner capabilities.
Development of many product variants, starting from a common base of versionable lifecycle artifacts, is a fact of life for many product-centric organizations. Each variant spawns its own branch of parallel development. This is further complicated if the variants themselves are developed using a strategy of multiple parallel releases. In this case, each variant can have its own family of parallel release development branches.
This article describes two branch management patterns that you can use to help manage multistream variant development: (1) sequential releases with multiple variants per release and (2) multiple variants with parallel release streams per variant. Each pattern is based on foundational patterns that are described in other articles in this series. Each pattern can be implemented using the IBM CLM and CE solutions.
The IBM CLM and CE solutions provide the global configuration capability, which helps you manage the hierarchies of multi-domain lifecycle artifacts that describe and support the development of each variant. In this article you learned about three approaches for creating the configuration hierarchy for a new variant: (1) fortuitous reuse, (2) the application engineering pattern, and (3) the domain engineering pattern. Consider your organization’s philosophies about asset reuse and solution engineering while you decide which of these patterns might be best for you.
For more information
See the other articles in this series:
- Defining your component strategy
- Patterns for stream usage
- Single stream strategy
- Multistream concurrent release development strategy
About the author
Todd Dunnavant, Ph.D., P.E., is a Principal Solution Architect with IBM Watson IoT Services. He has 20 years experience in successfully transforming how software, systems, and product engineering teams work. For the past 6 years, Todd has focused on realizing these transformations using IBM’s Jazz-based products. More recently, Todd has helped multiple product-centric companies adopt the lifecycle configuration management capabilities of the IBM IoT CE tool suite. He can be contacted at firstname.lastname@example.org.
© Copyright IBM Corporation 2017