Level: Introductory James Densmore, Certified IT Specialist and Western Regional Practice Lead for Solutions Architecture, IBM
14 Jul 2006 from The Rational Edge: The author proposes two methods for managing multiple versions of requirements across multiple product releases. The first method employs IBM Rational RequisitePro or other requirements management tool. The second method utilizes a change management facility, e.g., IBM Rational ClearQuest, in combination with the requirements management tool.
 In IBM Rational's work with its clients, we routinely deal with requirements that vary from one release to the next. As a result, a tester is often working with the current release and therefore is looking at an "older" version of a given requirement than either of, say, two developers, each of whom is working on his or her own branch toward a different future release.
This poses an interesting management problem. In a large system, there may be many requirements, more than we easily can remember to change at the appropriate time. Ideally, when a branch is merged, the requirement is updated correctly. Traces to tests affected by that requirement should be made suspect, so that the testers are informed automatically that the test cases may also require changes.
In this article, I present two methods to address this problem.
Background
One might think that software configuration management (SCM) tools that implement file versioning, such as IBM Rational ClearCase, would handle this need. Unfortunately, such versioning capabilities cannot be applied to requirements unless we place exactly one requirement in a file, and maintain a separate file for each and every requirement -- and that is extravagantly impractical! Most requirements management tools maintain a history of each requirement, but they do not do versioning. The only complete view of requirements offered by these tools is "Main/Latest."
Several methods for dealing with versioning requirements have been tried in the past, including duplicating requirement repositories and copying requirements documents into temporary documents containing requirements text (which lack attributes and traces). These methods have not been satisfactory. Either they are labor intensive and error prone, or they cripple the very features of the tools needed to successfully manage requirements as they change in response to market forces and other factors.
Let's consider two methods for maintaining traceability of changes to requirements across multiple product releases. The first technique uses IBM Rational RequisitePro. The second employs RequisitePro as well as IBM Rational ClearQuest. Both work through a straightforward discipline in writing the requirements involving only the basic features of the products. While we have used IBM Rational products, these methods should be extensible to other products with similar capabilities.
Method 1: Be all inclusive
The first method relies on a straightforward discipline that expands the conventional rules about how to define requirements. Currently, few rules generally apply to requirements definition. About the only consistent rule is what sometimes is called the Zen Rule: A requirement must be a statement about something required. To improve this method, we need to expand the scope of our requirements: A requirement must always describe what is required over all points in time, both now and in the foreseeable future (so far as we know). In addition to facilitating our method, this new scope also adds value because the requirement becomes a statement of everything we need to know over time about the essential need that it describes. This can help significantly in the architecture and design of the system.
Suppose, for example, that a system requirement is for four widgets in the next release, and six widgets in the release following. Then our method indicates that the requirement should be written to state that complete need: SUPP42: The XYZ application shall have four (4) widgets for the 30-June-2006 release, and in subsequent releases shall have six (6) widgets.
Note that this does not mean we have to include information about the past when we update requirements. It would be no problem from a requirements analysis point of view if, on 1 July 2006, we happen to change the requirement to read as follows: SUPP42: The XYZ application shall have six (6) widgets. If we did so, the previous version of the requirement would be stored in RequisitePro in the history for SUPP42 and therefore still accessible. More importantly, the mechanism described below will inform us that a change has occurred.
A new requirement attribute
To facilitate this method, I propose the addition of a new attribute for every requirement type whose requirements might be used on releases with multiple versions. Let's call this attribute Versioning Review Date. We define the meaning of the Versioning Review Date for each requirement as the date on which the text of the requirement is subject to review by a requirements analyst for versioning purposes. When it is blank, then no review is currently necessary for that requirement. Any requirement whose text refers to multiple states over time should be then assigned a date value by the requirements analyst. The Versioning Review Date should correspond to when the analyst anticipates that some part of the requirement will change or become obsolete.
Example
The following example illustrates how the "all inclusive" method works. The first column in Table 1 holds the date on which a change shown in each row is made. The Versioning Review Record column shows whether a change request is open; if so, it contains the value for a Version Review Date record attribute. The Requirement Text column shows the current text of the requirement. The Test Case column holds the value of the supplementary requirement that is to be tested by the test case.
A blue arrow represents a trace, and an arrow with a red slash represents a suspect trace. As with other appropriate pairs of requirements and test cases, an analyst previously has noted (with a facility called traceability) that this requirement and this test case are related. The relationship is simple: If one changes, the other might change and therefore is in need of attention from an analyst. The requirements management tool notes that the requirement has changed. Therefore it makes the trace suspect to indicate that the test case needs attention. Part of our method involves regularly querying for suspect traces. They comprise an early warning system to ensure that the impact of changes to requirements across product versions are analyzed and dealt with as needed.
Finally, just to keep things simple, let's assume that the application to which the example requirement applies has three releases: August 31, September 30, and October 31.
Table 1: Example of the "all inclusive" method
Method 2: Using a change request manager
The alternate method is a twist on the "all inclusive" method described above. It leverages the availability of IBM Rational ClearQuest, or any change request manager that supports traceability to requirements. There are three basic steps to this method:
- We write our requirements so that they always describe what is required over all points in time, as in the "all inclusive" method.
- Instead of creating a new requirement attribute, the change-control manager creates a change request record type containing activities related to the need to change a requirement.
- The requirements analyst associates a record of the new type with requirements that change from one release to the next.
For each requirement that contains multiple necessary states from now and into the future, a requirements analyst opens a change request record representing a review activity. Many requirements might be associated with each such review activity. The review activity should occur on or after a specific date on which the text of the requirements is to be reviewed by a requirements analyst for versioning purposes. The record should contain a review date. The date should correspond to the timeframe when the analyst anticipates that part of the requirement will change or become obsolete.
Of course, the advantage here is that no one has to remember to run queries in the requirements management tool to see what requirements should receive a versioning review. The change management tool now contains this information.
Example
In the example shown in Table 2, the first column holds the date on which the change shown in each row is made. The Versioning Review Record represents a change request record that contains the date of review for the requirement(s) to which it is traced. The remaining columns hold the same information as in Table 1, in the previous example. Note that using change requests in this way can simplify the logistics because one record can represent the need to change many requirements.
Again, assume that the application to which the requirement applies has three releases: August 31, September 30, and October 31.
Table 2: Example of using a change request manager
A real-life scenario: Has something like this happened in your shop?
For a defense application, Ephemeris Information Systems Inc. (not the company's real name!) was late in the development cycle for a new Ephemeris Database for tracking the orbital information associated with the many artificial satellites in Earth's orbit. Tracking space junk as well as active satellites is important for anyone operating in space; even unmanned vehicles are extraordinarily expensive, and if they hit another object in space, it's likely to cause a disaster. Tests on the database had gone well. In particular, it was important for queries on a particular attribute (let's just call it Cheese, shall we?) to occur quickly, and tests were showing that queries on this attribute were slightly exceeding performance specification.
One day, a tester working on the program noted that a requirement specifying the possible values of this Cheese attribute had recently changed. No longer was it two bytes. Up to eight bytes would be needed to store the possible values. Concerned about whether the needed change to the schema had yet been made so that he could build and execute the appropriate tests, he walked down to his friend in the development shop and asked if the change to the requirement had yet been noted.
The developer looked horrified. She asked who had made the change and picked up the phone to call the analyst: "How come we didn't hear about the change to Cheese earlier?" The analyst responded, "We didn't know initially that the values would be that large, so the original requirement was just for those two bytes. Soon after development started, we learned about the need for bigger values, but we understood that a prototype was being constructed first, and two bytes was enough for the prototype, so we left the requirement alone. Unfortunately, we forgot to make the change until recently. We just forgot."
The developer said thanks and hung up. Over the next few days, attempts were made, but no one could find a way to resolve the issue looming over the project. The developer's worst fears were realized. At two bytes, the database automatically cached large numbers of Cheese values, resulting in query performance that was acceptable -- the performance exceeded the requirements by 35 percent. However, early in development, it had been recognized that if the Cheese values were larger than four bytes, a different database organization, a different schema, would be needed to achieve the needed performance. "Aw, there's no way Cheese will ever be more than four bytes," someone said. In fact, it was already known that under some circumstances, eight bytes would be needed. Development proceeded with the more easily implemented schema, so that a couple weeks' development time associated with the more difficult, but presumably unnecessary, schema could be saved.
Now, as the need for the more complicated schema was clear, many weeks of development time were lost building data converters for the old schema. Fortunately, query management was isolated into a good subsystem design, so redesigning the queries for the new schema was less costly. However, in the end, while somewhat more complex, the new schema was part of a much better data architecture, making a number of unforeseen changes from the customer that occurred later in the program far easier.
To summarize, the two needs -- one only for an early iteration and one necessary for the later production system -- should have been made known in advance. Development for the prototype would have been slightly more costly, but the team would have vetted a more complex, but much needed data architecture that would soon show its value in netting high-performance queries.
Conclusion
Requirements versioning is the process of documenting the anticipated need for multiple changes to specific requirements over time. The best reason to implement requirements versioning, on most projects, is to enable the team to determine exactly how and why a requirement has changed from one release to the next, so that test cases can be modified accordingly. Requirements versioning also streamlines the requirements-auditing function, helping to ensure that the product meets the requirements and thereby improving quality. Finally, it enables the architects and designers to see the entire eventual scope of the system, so far as it is known, facilitating robust choices for the architecture and system design.
As the above methods and corresponding examples illustrate, it can be straightforward for development teams to implement requirements versioning using existing tools simply by changing how requirements are written and then adding some new processes.
About the author  | 
| | Jim Densmore is a regional practice lead for Solutions Architecture with IBM Rational. His responsibilities include enabling clients in the areas of organizational transformation and the engineering of complex systems. Before joining Rational as a sales team tech rep in 2000, he spent more than twenty years involved in the architecture, design, and development of high-fidelity, real-time combat simulations and real-time telecommunications software. He holds a BA from the University of California, Los Angeles, and an MS in computer science from the University of Maryland. |
Rate this page
| 
