What you need to know first
This article focuses on document-based requirements, such as use case specifications. Database-based requirements might need different strategies for development in parallel.
The IBM® Rational® RequisitePro® documents must be stored in Microsoft® Word® format (not in Rational RequisitePro format), and the contained requirements must not have hierarchical (parent-child) relationships.
The scenarios described here have been tested with Rational RequisitePro Version 7.1.0 and Microsoft Office 2003, running on Microsoft® Windows® XP, Service Pack 2. To get familiar with the basic ideas and techniques, it is best to set up a test environment, because some of the actions could irreversibly damage data if they are performed incorrectly.
Rational RequisitePro has no branching or merging mechanism as IBM® Rational® ClearCase® does, for example. Storing RequisitePro documents in ClearCase to benefit from its branching and merging capabilities would not resolve the problem, because the ClearCase-Microsoft Word merge manager does not consider the embedded requirements that are stored in the RequisitePro database.
The only solution is to use native Rational RequisitePro functionality and to create separate instances of RequisitePro documents and requirements. With these separated instances, teams can work independently and then bring together the changes afterward. Additional requirement attributes can help in managing where a requirement was branched off from and where it was merged to. A trace relationship between the original requirement and the branch requirement can help you stay in touch with changes that are made to requirements by other teams.
Microsoft Word includes compare and merge functionality for documents and can be used for merging different versions of a document.
For Microsoft Word, it makes no difference if the document extension is different from .doc (such as .ucs for use case specification, for example). However, Word does not work with the Rational RequisitePro format for storing documents, so this has to be switched off.
- From the RequisitePro menu, click File > Project Administration > Properties.
- From the Project Properties window, select the Documents tab, and remove the check from the "Save documents in RequisitePro Format" check box (see Figure 1. Changing RequisitePro document format).
Figure 1. Changing RequisitePro document format
To increase the support of Rational RequisitePro for branch or merge scenarios, add two additional attributes to every requirement type that will be affected by branch or merge action.
- From the RequisitePro menu, select File > Project Administration > Properties.
- From the Project Properties window, select the Attributes tab, and add two additional text attributes named
merged to(see Figure 2. Add supporting attributes to affected requirement types). They will hold the information about which requirement the requirement was branched off from and which requirement it has been merged with.
- Apply a default value, for example a hyphen (-), to make the attributes display that they are currently holding no value.
Figure 2. Add supporting attributes to affected requirement types
Projects with parallel development are usually organized according to teams or releases. The project’s organization should be reflected in an appropriate package structure in RequisitePro. In this example, we’ll organize the project by releases, R10 and R11, as Figure 3. Reflect the project organization in the package structure).
Figure 3. Reflect the project organization in the package structure
Branch a Rational RequisitePro document
To keep this example, simple there is only one use case specification in the R10 release package. An R11 branch will be branched off from the R10 release (modifying Use case requirements for the upcoming 1.1 release of a product). The use case specification contains only two requirements (see Figure 4. Starting situation in RequisitePro database and Figure 5. Starting situation in a RequisitePro document):
- UC1: Withdraw cash
- UC2: There is an active…
Figure 4. Starting situation in RequisitePro database
Figure 5. Starting situation in a RequisitePro document
To branch the existing Rational RequisitePro document to the R11 release:
- Open the R10 RequisitePro document, and, from the Microsoft Word menu, select RequisitePro > Document > Save As, and store the document in native Microsoft Word format.
- From the RequisitePro menu choose File > Import.
- In the Import Wizard dialog box (Figure 6. Branching – Import document), select Microsoft Word document and then browse to the previously stored file and click Next.
Figure 6. Branching – Import document 1, Withdraw Cash R10.DOC
- For the content to be imported, select Document only (Figure 7. Branching – Import document 2) and then click Next.
Figure 7. Branching – Import document 2
- Provide a meaningful name for the new Rational RequisitePro document. A good approach is to add the release tag to the name.
Note:Names for RequisitePro documents must be unique within each project.
- Select the appropriate document type (use case specification in this case), and click OK (see Figure 8. Branching – Import document 3).
Figure 8. Branching – Import document 3
- In the Create Document window, select Yes.
- The bookmarks in the imported document are needed for identification of the included requirements, so select No in answer to "Do you want to remove these bookmarks?" because you need to keep bookmarks of embedded requirements (Figure 9. Branching – Import document 4).
Figure 9. Branching – Import document 4
- Finally, select the Commit button (Figure 10. Branching – Import document 5).
Figure 10. Branching – Import document 5
After the document has been imported, there is an exact copy of the original Rational RequisitePro document (including tagged requirements as shown in Figure 11. Branching – Branched document and requirements), and the R11 release package contains its own RequisitePro document (see Figure 12. Branching: R11 branch of R10).
Figure 11. Branching – Branched document and requirements
Figure 12. Branching: R11 branch of R10
Notice that , during the import of the document, new requirements have been created. The newly created requirements are not copies of the original requirements but new instances with applied default values. Check whether the original requirements have attribute values that need to be entered for the copies of the requirements also.
The R11 release package now contains a separate requirements document together with its requirements. They can be edited entirely separately from the original requirement document and requirements.
Track the original and branched versions
In this simple example, it is easy to track the original and branch requirements. In real life projects with hundreds or thousands of requirements, you need a tool to help with oversight.
One mechanism that can be used is to establish a trace relationship between the original and the branch requirement (Figure 13. Tracking original and branch requirement by trace relationship). This serves two purposes:
- Documentation is established for what the origin of the branch requirement is (the direction of the trace relationship could be from the original to the branch requirement).
- A mechanism is established for notifying team members if changes to the requirements are made on a different branch (in case of complex use cases, it is good to keep in touch with the other teams).
A small limitation is that a trace relationship is not allowed to be circular. Therefore, you are limited to documenting either a branch or a merge relationship.
Figure 13. Tracking original and branch requirement by trace relationship
An alternative mechanism is to use additional attributes for managing branching or merging. You can document the status of the requirement by adding a text attributes to the concerned requirement types that say "originates from" and "merged to." No entry in originates from means that it is an original requirement. No entry in merged to means that the branch requirement hasn’t been merged yet (seeFigure 14. Using attributes for managing branch/merge).
Figure 14. Using attributes for managing branch/merge
Merge a RequisitePro document
If an existing document was branched, it is usually changed in some way. The change could be a modification, addition, or deletion. We’ll show you how to perform these three changes on our branched requirement document and work through the merge process so that you can see how they can be incorporated in the original requirements document later on. Here, there’s a modification in the use case title: the requirement UC4 has been removed and the requirement UC5 has been added (Figure 15. Modification on branched requirements document)
Figure 15. Modification on branched requirements document
After the modifications have been applied from the Microsoft Word menu, we select RequisitePro > Document Save to submit the changes to the database.
Now, merge these changes into the original requirements document. First, you need to create a temporary document.
- From the Microsoft Word menu. choose RequisitePro > Document Save As, and store the document in native Microsoft Word format.
- Open the temporary document and, from the Word menu, select Insert > Bookmark.
Navigate through the bookmarks by double-clicking them. Even though there is no RequisitePro document, specifically, there’s still one bookmark for each requirement in the requirements document. In this requirement document example, we have two bookmarks. One bookmark is for the modified requirement (Figure 16. Bookmark for modified requirement). The other is for the added requirement (Figure 17. Bookmark for added requirement).
- Remove any bookmark that is related to the modified requirements, because you don’t want RequisitePro to consider them during the import. The result should look like Figure 18. Cleaned bookmarks.
- Save the document when you are finished.
Figure 16. Bookmark for modified requirement
Figure 17. Bookmark for added requirement
Figure 18. Cleaned bookmarks
You can merge the modified temporary document into the original document.
- To retrieve the location of the original document, right-click the document and select Properties.
- Next, in the Document Properties window, select the General tab.
- You can copy the location of the document from the Directory field (see Figure 19. Document properties).
Figure 19. Document properties view
- From the temporary document, from the Microsoft Word menu, choose Tools > Compare and Merge documents.
- In the next window, browse to the original document (Withdraw Cash R10.ucs).
The difference can be resolved by accepting or rejecting the changes. Basically, there are three different scenarios to consider (Figure 20. Merging the original and branched document)
Scenario 1: Modifications to an existing requirement
The requirement is present in both the original and the branched requirement document. You want to get the changes made to the branched requirement into the original requirement. To do so, the original bookmarks must remain in the original document. When resolving the differences, reject any changes that refer to format changes or additions or deletions of use cases. Just accept the modifications being made on the text within the bookmark (if you want to get the changes back into the original; if not, reject them also.)
Scenario 2: Removal of requirements
The requirement is present in the original document but was removed in the branched-off document. If you want to remove the requirement in the original document, accept all changes related to this section. If that is not what you want, reject them completely.
Scenario 3: Addition of requirements
The requirement is not present in the original document, and it was added in the branched-off document. If you want to add the requirement in the original document, accept all changes related to this section. If you do not want to do that, reject them completely.
Figure 20. Merging the original and branched document
For the sake of this example, we want to bring the modification, the deletion, and the addition to the original document. Therefore, after accepting and rejecting the changes as described, the final, merged result should look like Figure 21. Merge result in.
- Save the original file when you are finished.
Rational RequisitePro is not involved in the merge process, so it cannot recognize the changes until you open the original document from RequisitePro.
Figure 21. Merge result in Microsoft Word
- Open the original file from the RequisitePro client. RequisitePro will detect the changes made to the document by the Microsoft Word merge process (Figure 22. RequisitePro detects changes from outside).
Figure 22. RequisitePro detects changes from outside
- Click Yes to update the database in accordance with the modified original file.
- Provide a meaningful description at the prompt (Figure 23. RequisitePro request a change description).
Figure 23. RequisitePro request a change description
During the update process, RequisitePro detected that one of the bookmarks belongs to a requirement located in the branched document. RequisitePro requires a unique location for any given requirement, so it gives you the choice to either cut and paste the requirement from the other document or create a copy, instead. Bear in mind that this is a complete copy of the requirement text and the attribute values.
For this example, create a copy to avoid pulling the requirement from the R11 release (Figure 24. Requirement Found view and options within RequisitePro ).
Figure 24. Requirement Found view and options within RequisitePro
The final merge result in the R10 requirements document will look like Figure 25. Merge result in Rational RequisitePro.
If there are modified requirements, the attribute values will not be automatically copied as they were for added requirements. Instead, the attribute values need to be examined and aligned manually. As a last step, update the branched requirement attributes to reflect the fact that a merge was performed (Figure 26. Merge state displayed by attributes).
A clever combination of views, filtering on suspect links (changes have happened) and attributes (merge was not performed yet), could provide insight into which requirements are different and have to be merged.
Figure 25. Merge result in Rational RequisitePro
Figure 26. Merge state displayed by attributes
Working in parallel on document-based requirements seems to add more flexibility to projects. But working in parallel also always means additional effort when it comes to resolving concurrently made changes. Even though Rational RequisitePro was not designed for such an environment, thus has no branch or merge capabilities included, it can provide support for this scenario to some degree. Because of the limitations, the use of such a scenario should be limited to projects where it is essential.
Get products and technologies
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Browse the RequisitePro page on developerWorks for links to technical articles and many related resources. The developerWorks Rational software landing page is also a good starting place.
- Watch one of the Rational RequisitePro demos (scroll down).
- Explore the RequisitePro Product Name Information Center.
- Join the RequisitePro forum to ask questions and participate in discussions.
- Download Rational RequisitePro for a free trial.
- Check out agile development capabilities of IBM® Rational® Requirements Composer, which can help your entire team define, update, and management requirements throughout the product development lifecycle.
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download trial versions of IBM Rational software.
- Download trial versions of other IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.