Take control of your requirements projects with Configuration Management
IBM Rational DOORS Next Generation
Learn how to use configuration management in the Requirements Management (RM) application to manage streams, baselines, and change sets, to compare configurations, and to perform other configuration management tasks.
In the labs that follow you will perform the following tasks:
- Create a baseline, in the requirements management stream, to represent and preserver the starting state of the project.
- Make changes within the requirements stream, representing ongoing development efforts
- Compare the current stream of development to a baseline in order to assess what changed since the baselined.
- Create a new stream of development (a variant) from a baseline.
- In the variant stream, make related changes within a change set, and deliver the change set to the stream.
- Share your change set from the variant stream to the original stream.
To successfully complete this tutorial, at a minimum you should be aware of the following terms
- Configuration: A unique set of versions of artifacts. Configurations commonly identify one version of each artifact in the set. The artifacts can be unchanging (from a baseline) or open to change (in development). In some systems, configurations can be hierarchical, so that they contain other configurations.
- Stream: A configuration that is.
- Baselines: A configuration that is immutable (unchangeable).
- Change set: A group of related changes to artifacts in a workspace or stream.
If you need more information, consider these resources:
- An introduction to basic concepts of Configuration Management across the Engineering Lifecycle is presented in this video: Work smarter with configuration management. Part 1: Introduction. Watch It on YouTube or developerWorks.
- A brief overview of key configuration management concepts and terminology of the IBM IOT solution, are presented in this CLM global configuration - Overview of concepts and terminology video (Watch it on YouTube or developerWorks).
- For an overview of the main Configuration Management concepts and capabilities, see the Knowledge center topic: Configuration management: concepts and capabilities.
- For a glossary of terms, including the main terms related to configuration management, see the Knowledge center topic: Glossary for the Rational solution for Collaborative Lifecycle Management (CLM).
Now let's consider the Rational DOORS Next Generation interface.
Two menus are relevant to configurations:
- Use the configuration management menu to search for and switch to a specific configuration, open and edit the current configuration, and compare configurations.
Figure 1. The Configuration management menu
- From the Administration menu, select Manage configurations, to explore the configurations. The option opens a page where you can navigate or create configurations (streams and baselines) in the project area.
Figure 2. Use the Manage Configuration option in the Administration menu to navigate the configuration.
Figure 3. The tutorial uses the Jazz.net sandbox, 6.0.1 M2 with configuration management.
When you create your sandbox (see video) you need to provide a name for your project. In this tutorial, the project name is JPK's AMR Project. Your project name will be different. For example, <your jazz.net id> AMR Project.
Notice that several projects areas were created within the sandbox (Figure 4)
- JPK's AMR Project (Requirements Management)
- JPK's AMR Project (Change and Configuration Management)
- JPK's AMR Project (Quality Management)
- JPK's AMR Project (Global Configuration)
Figure 4. Projects that are created in the sandbox. Your project names will be different.
Click on a project in this list (for example JPK's AMR Project (Requirements Management)). This action automatically logs you in to the Jazz.net sandbox by using your Jazz.net login, and the selected project opens. When you log in to your Jazz.net sandbox, use the home menu to navigate to the projects.
You will receive an email to (at the account that is associated with your jazz.net id) with links to your sandbox project areas. Save this email, or bookmark your sandbox URLs.
Figure 5. Some of the projects as reflected sandbox’s Jazz team server.
The Jazz.net sandbox with configuration management is only a subset of the AMR system, providing enough to information to demonstrate key aspects of the solution.
In these exercises, the focus will be the requirements management project. By the end of the exercises, you will have created baselines, parallel streams, change sets, and delivered the change sets across different streams.
The requirements management project, JPK's AMR Project (Requirements Management) (your project name will be different), has one development stream, also named JPK's AMR Project (Requirements Management). Within this stream, there is a module: AMR System Requirements Specification that contains requirements.
You can reset your environment at any time, and restart this tutorial. This tutorial assumes that you start from a fresh environment.
Figure 6. Jazz.net sandboxes can be deleted.
Lab 1 Work with streams and baselines
Baselines captures a meaningful state of artifacts, such as an approved state, or a release, or perhaps a specific point of time. Watch this video on baselines with Rational DOORS Next Generation (on YouTube or developerWorks).
1.1 Create baselines to capture the state of your requirements management project
You will create a baseline to capture and preserve the starting point of your development effort.
Figure 7. Baselines are created for the development streams.
- From the home menu (see Figure 5), switch to the JPK's AMR Project (Requirements Management) project; remember, your project name will be different.
- From the CurrentConfiguration menu, select Create Baseline.
- In the Create Baseline window, provide the following information:
- Title: AMR(RM) Starting Point
- Description: This is the starting state of the requirements management project in the Jazz.net sandbox
- Click Create.
- Click OK when the window informs you of the successful creation of the baseline.
- Notice that you are still in a stream configuration; you did not switch to the baseline. While in the stream configuration you can still edit. If you switch to the baseline, you can no longer edit the baseline.
1.2: Make changes within a stream
You have baselined your requirements project. Now you will make some changes within the requirements stream, representing continuing requirements management efforts such as or updating existing requirements or collecting additional customer requirements.
Figure 8. The baseline represents an immutable state of your project, but you can continue your development efforts on the streams.
- Notice that you are in a stream.
- From the Modules menu, click Browse Modules.
- Open the AMR System Requirements module by clicking its name.
- Using your DOORS Next Generation expertise, make some changes to your project:
- Edit the requirement. It currently says this:
The handheld device shall have the ability to search for accounts by Last Name, Service Address, Meter Number, and Unread Meters.
You need to add the ability to search by phone number:The handheld device shall have the ability to search for accounts by Last Name, Service Address, Meter Number, phone number, and Unread Meters.
- With the artifact still selected, use the right sidebar to set its Status attribute to Approved. Here are some more details of how to accomplish this:
- With the artifact selected, from the right side bar, click the Selected Artifact tab, and then click Edit.
- Locate the Status attribute and from the pull-down menu, select Approved.
- Scroll to the top of the side bar, and click DONE.
- Locate this requirement:
Display information shall include: total number of accounts in collection route, number of read accounts, number of unread accounts, the address of each account. For completed (read) accounts, the display information shall include: the date and time of the last reading, summary of usage data, and the id of handheld reading device.
- Edit the requirement to also display the phone number:
Display information shall include: total number of accounts in collection route, number of read accounts, number of unread accounts, the address and phone number of each account. For completed (read) accounts, the display information shall include: the date and time of the last reading, summary of usage data, and the id of handheld reading device.
- Edit the requirement. It currently says this:
- (Optional) The preferred way of making changes to a stream is to use a change set. When you are editing directly in a stream, Rational DOORS Next Generation actually creates and delivers change sets with every change. A more optimal solution (one that we will explore later), is to group related changes within a change set. To see the change sets that were created and delivered in the stream, follow these steps:
- From the Administration menu, select Manage Configurations.
- Click the stream name (example: JPK's AMR Project (Requirement Management).
- Click the Change Sets tab. Click the Select to include delivered change sets icon. The changes you created will be at the top of the list identified with your user name.
- Return to the module view by selecting Modules > Browse Modules.
1.3 Compare a stream and a baseline
Configurations, which include streams and baselines, can be compared with each other. Comparisons are very useful when trying to assess what changed.
- From the Current Configuration menu of the requirements management project, select Compare Configuration.
- In the Select Configuration Context window,
- Select Baseline (to filter on baseline configurations)
- Type * (to list all baseline configurations)
- Select AMR (RM) Starting Point
- Click OK
- In the wizard, you can review the differences between the stream and the baseline.
- Confirm what you are comparing (the stream to the baseline), and click Next >.
- The next page shows a summary of the changes in the project properties. You did not make any such changes, so click Next.
- Now the wizard shows that there are no changes in the folder structure of the project, so click Next.
- You can see the changes to the artifacts. Click the changed artifacts on the left to review detail of changes to that artifact on the right.
- When you finish your review, click Finish.
A stream can be baselined at any time to capture the state of the project. Baselines are an immutable (unchangeable) version of the artifacts, as of the time that the baseline was created. Users can switch to the baseline, compare it to other streams or baselines, and even start new streams of development from a baseline. Because a baseline represents a known state of your system that cannot be changes, baselines are very useful when managing multiple product variants, or even multiple versions of the same project or product. As you will see in the next exercise, multiple product variants can branch new streams of development from a common point (represented by the baseline), sharing (not clone and own) all requirements up to that point. The changes in a stream of development are local to the stream. The changes in one stream will not affect other streams, unless changes are delivered to other stream.
Lab 2 Create a stream from a baseline
The AMR teams are using multiple streams to manage variability across the product line. Separate streams will be used for the Mobile and Grid products. Figure 9 shows a conceptual view of the configuration dependencies.
Figure 9. Streams are used to manage variability across the product line
In this lab you will create new development streams to manage variability between the Mobile and Grid product variants. You will create a variant streams from a requirements baseline. Both streams will be using the same requirements, but each stream will have its own version of those requirements. Because we are creating the variant stream from a baseline, all changes since the baseline will not be in the newly created stream. (You could have created a new stream from the JPK's AMR Project (Requirements Management) stream, which would have created an automatic baseline of the stream at that point of time.)
- Switch to the baseline configuration, AMR (RM) Starting Point, as follows:
- From the Configuration menu, select Switch.
- In the Select the Configuration Context window:
- Choose the type: Requirements Management Configuration.
- Focus on Baseline.
- Enter start to filter the list of baselines.
- Locate and select the AMR (RM) Starting Point configuration. This will become your starting point for the Grid effort.
- Click OK to switch to that baseline configuration.
Selecting a configuration loads the application with the versions of the artifacts in that selected configuration. The name of the selected configuration is shown on the banner. An icon indicates the type of configuration. As seen from the icon, AMR (RM) Starting Point is a baseline.
Baselines cannot be edited. They are a reference point that cannot be changed.
- From the Configuration Management menu, choose Create Stream.
- In the Create a Stream window,
- Enter the stream name: AMR(RM) Grid.
- Select the Switch to the new stream check box, and click Create.
The new requirements stream for the AMR (RM) Grid product is created and opened in the editor. The new stream name is shown in the banner.
The stream is not a physical copy of the requirements; it is not a clone-and-own copy. Each stream references the requirements, each at a particular version. The result is that teams can work in their streams as needed, and changes can be shared with other streams (if needed). They can compare configurations with each other to see how they are different.
With streams, teams can manage variability between different products, or even different versions of the same product. It is important to note that different steams share the same requirements; this is not a clone-and-own solution, but true reuse. Changes are tracked within the different streams, and at any point, streams can be compared to each other or to baselines, and even synchronize changes between them.
Lab 3 Control change with change sets
Sometimes, you need to collect related modifications to shared artifacts, and deliver them as a set. Here are some possible reasons:
- The change is not trivial, and will require several changes. You do not want to disturb current development until the change is ready.
- The change needs to be approved before it is made generally available.
- The change will impact other streams; you may need to share this information with other streams.
- In a collaborative development environment, you accept changes from another stream or baseline so that you can use them in the stream where you are working.
A change set is a collection of related modifications to shared artifacts that are delivered to a stream, and can later be delivered to other streams.
When you finish making changes, you can either deliver your change set to its destination stream or discard it. Only delivered change sets will be available to other streams.
More than one person can work on a change set.
As you saw earlier, each time you make a change directly on a Rational DOORS Next Generation stream, the application creates and delivers a change set automatically, and your changes are available immediately to other team members who share the stream.
In this exercise you will create a change set within the AMR (RM) Grid stream that will group together a number of changes to the requirements. In a future exercise you will deliver the change set to the JPK's AMR Project (Requirements Management), demonstrating that requirements are shared across streams.
Figure 10. A change set is a collection of related modifications to shared artifacts that are delivered to a stream, and can later be delivered to other streams.
3.1 Create a change set for requirements
- From the current configuration menu of the AMR (RM) Grid stream, select Create Change Set.
- Name the change set:
Meter Interface requirements, and click Create.
- Verify that the change set is already selected as the current configuration.
3.2 Make changes within a change set
You are in the change set, therefore, all changes you make from now on until you deliver or discard the change set are automatically collected into this change set.
- Open the Current Configuration menu and see the operations you can do with your change set. In this "sunny day" exercise, you are going to make some changes and will then use Deliver Change Set. You can see in the menu that you could also discard the change set, or compare the change set content with the stream it is based on.
You can switch to a different configuration and make changes there without affecting the state of this change set, and you can return to this change set later to continue making changes.
To get the most value out of using change sets, make the changes accumulated in a change set cohesive – so they are all related, or for the same purpose. Note:
- Using your DOORS Next Generation expertise:
- Open the AMR System Requirements module.
- Locate this artifact: The handheld device shall provide for the means for the meter reader to manually enter a meter reading.
Double click the text to edit it by adding six-digit before meter reading. Then either press Control + S or click elsewhere to save the change.
- Add a new section after section 1.1.1 Handheld device, of type Heading, and name it Meter interface Unit.
- In the Meter Interface Unit section, add a new requirement, below as a child, with the following text: A meter will support two-way communication between the meter and server via a wireless network.
When you are making these changes, only someone else who is also working in this change set can see them.
When you have completed the changes, you could inform the team by using a work item that the change set is ready for approval. After the change set is approved, it is ready to be delivered.
3.3 Deliver the change set
The change set is ready to deliver to the stream. It contains three individual changes, grouped within a single change set. Delivering a change set causes little disruption to the team, which sees all changes only after they have been approved and ready to be delivered.
- Verify that the change set is already selected as the current configuration.
- Open the Current Configuration menu and click Deliver Change Set.
- Confirm that you want to deliver the change set by clicking Deliver the Change Set.
- In the wizard review the changes in the change set, and resolve any potential conflicts.
- Confirm what you are delivering (the change set, listed as the Source Configuration), and to where, listed as the Target Configuration. Click Next >.
- The next step of the wizard summarizes the changes in the change set. You can click the changed artifacts on the left to review the detailed changes to each artifact on the right. When you have reviewed all the changes, click Next >.
- The final step of the wizard is one last confirmation. Check that the information displayed in the summary is correct, and click Finish.
- Note that the current configuration is now the stream . Examine the changes to the artifacts to confirm that your edits are there. These changes are now visible to anyone else working in the AMR (RM) Grid stream.
In this lab you worked with change sets, so that the team could modify artifacts outside the main stream of development, and when they were ready, the team could either discard the change set or deliver it to the stream. After a change set is delivered to the stream, it can be shared with other streams, as you will see in the next exercise.
Lab 4 Deliver the changes from one stream into a different stream
The change set you created and delivered to AMR (RM) Grid is also valid for the JPK's AMR Project (Requirements Management) stream. Let's apply the change set to that stream.
Figure 11. Change sets can be delivered from one stream to another.
- Switch to the JPK's AMR Project (Requirements Management) stream.
- Open the Current Configuration menu and click Accept Changes.
- The changes in your change set have been delivered into the AMR (RM) Grid stream. Select that stream and click OK.
- The Deliver Change Sets wizard starts, showing the source and target. Click Next >
- Use the wizard to deliver all changes made to the stream since its most recent baseline, or be selective. Let's be selective. Click Select which change sets to deliver, and click Add.
- In the Select Change Sets window you see all the changes made in AMR (RM) Grid. Since all your changes were made within one change set, that is all you see here.
- Select the Meter Interface requirements change set, and click Add and Close.
The ability to selectively deliver changes between streams is very powerful.
- The change set is now shown in the list of changes being delivered into the target AMR (RM) Mobile US stream. Click Next >.
- The wizard shows the changes being applied. Click Next>.
- The wizard shows a summary of the source and target, for final confirmation. Click Finish.
- The AMR (RM) Mobile US stream has now been updated with the change set contents. Check, for example, that requirement 532 shows the text for the additional gas and electricity services.
Changes can be shared between streams, and change sets make this task a lot easier because they group together relevant changes, and given names that describe the changes they contain.
Configuration management of requirements is powerful. It helps you plan product variants that share the same requirements. It facilitates pushing changes to requirements across steams. It provides an easy way to compare different configurations to each other to identify differences. But most importantly, configuration management of requirements, as supported by Rational DOORS Next Generation, makes your teams more efficient and more productive.
- Blog: The benefits of requirements configurations
- Blog: Parallel development: even single product lines need it
- Blog: Smarter products, IoT, product lines and market segments (part 1)
- Blog: Breaking the tyranny of your engineering trend lines (part 2)
- Blog: Growing into a strategic approach to reuse (part 3)
- Blog: Taking a play from the software development playbook (part 4)
- Blog: Increase engineering efficiency with component reuse and global configurations
- Enabling configuration management in CLM 6.0 applications
- Tutorial: Getting started with IBM Rational DOORS Next Generation
- YouTube playlists