Introduction

If you work in a multi-team environment (this is usually the case when working in a Geographically Distributed Development, or GDD, project), and follow an iterative development approach (where the software development team starts implementing the first requirements baseline while the requirements team already works on the next baseline(s) for the next iteration(s)), you should work in parallel. You can use IBM® Rational® ClearCase® when working in parallel has to be supported.

Back to top

Working in parallel

For instance, your development team should not receive changes to requirements that are already in implementation. Another possible scenario is that your testing team may want to start with testing the prototypes very early in the development lifecycle. It makes sense to test the prototype against the original requirements. In most projects, the software development team usually cannot wait until the requirements team is done, and the test team cannot wait until the software team is done. In order to enable teams to work in parallel, it is sometimes necessary to implement the capability of working on different requirements baselines at the same time.

Currently, IBM® Rational® RequisitePro® uses ClearCase only as a versioning tool at a project-level scope. This means that a complete RequisitePro project can be archived "as is". There is no versioning of single RequisitePro requirements or documents supported out of the box.

You may want to display the history of RequisitePro documents in order to check who made changes, when the changes were made, and what the change actually was. This is supported by ClearCase for other file types, and this article will show you how ClearCase can handle RequisitePro requirement documents in a similar way.

This article will discuss some of the challenges that arise when you use RequisitePro and ClearCase for implementing parallel development and versioning RequisitePro documents, as well as possible solutions.

Back to top

Basics

This section will discuss the basic concepts of parallel development in ClearCase.

The concept of branching, merging, and comparing

ClearCase supports working in parallel by providing the capability of branching. A branch (shown as blue rectangles in Figure 1, following) is a linear sequence of versions (blue circles). By merging (indicated by the red arrow), different versions of a file can be combined. The differences in the involved version are revisited and selectively combined in order to produce a new version of the file.

In order to check what changes have occurred between two versions of a given file, you can use the compare functionality in ClearCase. You can easily compare by following these steps:

1. Select the two versions of the file
2. Right-click and select Compare to.
3. The compare tool displays the differences, as shown in Figure 2.

When your team works in parallel on different branches, often two people are working on the same file at the same time. Concurrent changes will be the result. ClearCase provides a very convenient and safe way to merge these different versions of a file into a consolidated version that contains all of the changes. It uses a 3-way merge algorithm, and is usually capable of merging different versions automatically. However, if there are conflicting changes, you need to resolve them manually, as shown in Figure 3.

When the differences have been considered, either automatically or manually, a merge arrow is drawn and ClearCase considers the differences resolved. Because of the merge arrow, the merge tool does not consider the versions to be different any longer, even if the content is actually different. Running the merge manager on a whole directory (tree) instead of a single file will make you aware of all files in that directory that have been added, deleted, or modified.

Magic files, element types, and type managers

The compare and merge functionality depends on the file format. ClearCase implements support for compare and merge functionality in a very flexible way using three basic concepts:

• Magic files
• Element types
• Type managers

When a file is added to source control, ClearCase assigns an element type to it. The element type is determined by the magic file. The magic file contains some criteria (usually file extensions), together with the element type to be associated. The element type has a type manager assigned. The type manager executes file format-specific operations when a ClearCase element is compared, merged, checked out, and so on.

The default.magic file is located at ccase-home-dir\config\magic in the ClearCase installation path. The details about the magic file format are explained in the ClearCase manuals. Listing 1 shows an excerpt from the default.magic file as an example.

# Match by name without examining data
core file : -name "core" ;
# (seems printable, but has binary at the end of it)
lisp_object object_module file : -name "*.lbin" ;
program compressed_file : -name "*.[eE][xX][eE]" | -name "*.bin" ;
object_module compressed_file : -name "*.[oO][bB][jJ]" ;
shlib library compressed_file : -name "*.[dD][lL][lL]" ;
zip_archive archive file : -name "*.[zZ][iI][pP]" ;
gtar_archive archive file : -name "*.gtar" ;
tar_archive archive compressed_file : -name "*.tar" ;
audio compressed_file : -name "*.au" | -name "*.aif" | -name "*.aiff" ;
audio file : -name "*.aifc" ;

Basically, the format is:

object_module compressed_file : -name "*.[oO][bB][jJ]" ;

where:

• object_module is a placeholder name
• compressed_file is the associated type manager to be used
• -name "*.[oO][bB][jJ]" is a file selector

You can explore the element types available in a ClearCase VOB with the ClearCase type explorer. Every VOB has a default set of element types, as shown in Figure 4.

There are dedicated element types for specific file formats. Exploring the details of the element types shows that some of them are derived from a super type manager. In addition, you can specify if elements of this type shall be considered for merging, as shown in Figure 5. Element type details.

General branching approach for supporting parallel development

A very straightforward approach for working in parallel is to work on a branch until the baseline is stable. When that is the case, all of the files on the branch will be labeled with the baseline label. A new branch (based on the preceding branch and label) is created. Then repeat: work on the new branch until the next baseline is stable. Again the files on the branch are labeled and a new branch is created, as shown in Figure 6

When an already finished baseline needs to be modified, you can make the changes on the baseline’s branch, and the changes get forwarded to succeeding baselines. Merging RequisitePro documents can cause problems, so you should do the following:

1. Manually check the documents out
2. Examine and resolve the differences
3. Check the file in
4. Manually create a merge arrow to indicate that the differences are resolved
   

This process supports the following scenario:

1. The requirements team starts working on baseline bl1 (the main branch, because the main branch cannot be renamed to rq_bl1 as would be appropriate).
2. When the requirements team is done with the baseline bl1, they label it RQ_BL1.
3. Based upon the branch for baseline bl1 (main) and the label (RQ_BL1), the next baseline (bl2) is created (branch rq_bl2).
4. The requirement team continues working on baseline bl2 (branch rq_bl2).
5. The software development team starts working on baseline bl1 (branch rq_bl1).
6. If the software development team needs to clarify or detail requirements, they will make the changes directly on the baseline bl1 (main branch).
7. Any changes that had to be made by the software development team for baseline bl1 (main branch) are manually “merged” (which means to check out the file on baseline bl2, consider any changes to reject or accept, check the file back in on baseline bl2 and draw a merge arrow) to baseline bl2 (branch rq_bl2).
8. When the requirements team is done with baseline bl2 (branch rq_bl2) they label it RQ_BL2.
9. Based upon baseline bl2 (branch rq_bl2) and the label RQ_BL2, the next baseline bl3 is created (branch rq_bl3).
10. The requirements team continues working on baseline bl3 (branch rq_bl3).
11. The software development team continues working based on the baseline bl2 (branch rq_bl2).
12. The software test team starts working based on baseline bl1 (main branch).
13. And so on.

Why RequisitePro documents should not be merged

Although ClearCase does support the merging of Microsoft® Word documents, do not merge RequisitePro requirements documents. Here are some possible scenarios that explain why:

• In case of an existing requirement, only the requirement text would be changed. The requirement name, if there is one, would stay the same. The attributes would also not be affected by the merge. The requirements may be renumbered and imported in a flat hierarchy.
• In case of new requirements, the document's default requirement type will be assigned (regardless of the original requirement type). The requirement attributes will be set to the attribute default values.
• If requirements have been deleted between two versions of a requirements document, and the versions are merged together, there is the potential that some requirements may disappear.

Deleting RequisitePro documents from the RequisitePro project

If a RequisitePro document is deleted from the RequisitePro project, the document extension will be set back to .doc. The RequisitePro document needs to be checked out beforehand in order to allow RequisitePro to perform this operation.

After the removal of the document from the RequisitePro project, you should clear the checkout on the file and execute a rmname operation on the cleartool command line in order to remove the file name from the project folder (do not use rmelem, because this would delete the complete version tree of the file). Do not merge different versions of RequisitePro project folders carelessly, because this could cause RequisitePro documents to disappear in other baselines if RequisitePro documents have been removed on other baselines.

Storing a RequisitePro project in ClearCase

There is compare functionality for Microsoft Word documents, but ClearCase needs to be made aware of the RequisitePro requirement document types and their specific file extensions. This can be done by creating a new ClearCase element type. In addition, you need to expand the default.magic file in order to provide a mapping from RequisitePro file names (extensions) to the new ClearCase element type. Because the existing ms_word type manager perfectly fits your needs, you can use it as the super type for your new element types.

Although the merging of RequisitePro documents is technically possible, it will likely result in database inconsistencies or data loss, because RequisitePro relies heavily on the formatting and the bookmarks in the documents.

Being able to compare different versions of a RequisitePro document will very much help you get an overview of how requirements evolved over time.

As far as relational databases are concerned, there is no compare and merge functionality available in ClearCase, and there is no simple way to implement it. This is because, for a Relational Database, not only content but also structure must be considered. If the merge is not performed correctly, database inconsistencies will occur.

There is a tool available at developerWorks (http://www.ibm.com/developerworks/rational/library/5066.html) that will allow you to compare RequisitePro projects on a project, requirement type, or requirement level, as shown in Figure 7.

Back to top

Implementing

This section will show you how to implement the principles discussed in this article.

Creating the element types

First, an element type for the RequisitePro document types in the RequisitePro project is created. The element type will

• Be based upon the type manager for ms_word and
• Prevent merging of files of this element type

You can easily achieve this on the command line by typing and executing the following:

Cleartool mkeltype -supertype ms_word -mergetype never -nc reqpro_docs@\REQS

For RequisitePro project files, another element type is created that will

• Be based upon the type manager for binary files (because some of the project files are binary)
• Prevent merging of files of this element type

Again, simply type and execute this command:

cleartool mkeltype -supertype binary_delta_file -mergetype never -nc reqpro_prj@\REQS

After adding the element types, the list should look like that shown in Figure 8.

Please verify that both new element types are configured to prevent merges. The Never consider elements of this type for merging option should be selected, as shown in Figure 9.

Modifying the default.magic file

In order to make ClearCase use the new element types, you need to expand the default.magic file, as shown in Listing 2. The default.magic file can be found at ccase-home-dir\config\magic. In order to avoid maintaining the default.magic file on every ClearCase client, there is an environment variable (MAGIC_PATH) available that you can be used to point to a central location.

# RequisitePro
# document types from RUP template
reqpro_doc : !-printable &-name "*.[uU][cC][sS]" ;
reqpro_doc : !-printable &-name "*.[vV][iI][sS]" ;
reqpro_doc : !-printable &-name "*.[bB][rR][sS]" ;
reqpro_doc : !-printable &-name "*.[gG][lL][sS]" ;
reqpro_doc : !-printable &-name "*.[rR][mM][pP]" ;
reqpro_doc : !-printable &-name "*.[rR][sS][kK]" ;
reqpro_doc : !-printable &-name "*.[sS][tT][rR]" ;
reqpro_doc : !-printable &-name "*.[sS][uU][pP]" ;
reqpro_doc : !-printable &-name "*[uU][cC][mM][gG]" ;

# RequisitePro 
# database files
reqpro_prj : -printable & -name "*.[lL][dD][pP]" ;
reqpro_prj : -name "*.[mM][dD][bB]" ;
reqpro_prj : -name "*.[rR][qQ][lL]" ;
reqpro_prj : -printable & -name "*.[rR][qQ][sS]" ;

The added lines should occur at the very top of the default.magic file, because processing stops if a matching file selector is found. Putting them first prevents a more general file selector from matching the RequisitePro files.

Disabling the Save documents in RequisitePro Format option

The Save documents in RequisitePro Format check box must not be selected, as shown in Figure 10. If this option is selected, RequisitePro documents cannot be processed outside of RequisitePro. This means that they cannot be compared by the ClearCase type manager.

Working in views

It is a good idea to use a centralized snapshot view on a Microsoft® Windows® share for a couple of reasons:

• All users need to work on the same set of documents for a specific baseline.
• RequisitePro stores the project name together with the storage location in the registry. Working with different (dynamic) views will confuse RequisitePro because of different storage locations (you can fix this by removing the projects and adding them again with the new location again, but that is cumbersome).
• Working in dynamic views with Microsoft Word needs good network performance.
• RequisitePro needs a Windows share for storing the RequisitePro project anyway.

Check in or Check out and Add to Source Control

You should keep the RequisitePro project files checked out. If they are checked in, RequisitePro considers the project to be in "read only" mode. The same is true when Word opens a checked in RequisitePro requirements document. In order to version any file that belongs to RequisitePro, the file should be checked in and out right away.

Because this is an uncomfortable procedure, there is a tool available that will handle this. Because it can be difficult to remember which file already belongs to the RequisitePro project, which needs to be added and which not, the tool determines the files to be considered directly from the RequisitePro project.

It adds RequisitePro requirement documents automatically to ClearCase if the file is still view private whenever a Checkin, Checkout or CreateVersion operation is performed (see Figure 11). Labeling of the complete project is also possible (only the files are labeled, not the directories).

Creation of RequisitePro projects

Because relational databases cannot be branched, you need to create a new RequisitePro project whenever a new baseline is created.

The creation of new RequisitePro projects is supported by the RequisitePro Baseline Manager. Because the RequisitePro Baseline Manager has no ClearCase interface, it is necessary to check out all of the project files on the new branch beforehand. The RequisitePro Baseline Manager does not allow other RequisitePro projects in the same storage location, so it is mandatory to delete all of the checked out files from the RequisitePro project folder.

Note: they must not be removed by ClearCase commands, but from either the Windows® Explorer or the command line.

It is necessary to replace them with the files created by the RequisitePro Baseline Manager, because otherwise ClearCase considers them new elements instead of new versions of already existing elements. The result would be a new version tree within ClearCase, which means that they cannot be compared.

The creation of a new Requisite project for every baseline will enable you to use existing tools to compare RequisitePro projects.

Naming the projects with respect to the baseline that they belong to will keep users from being confused. Ideally, this is done starting with the very first baseline.

Example

You create a new project that deals with requirements for a new starship generation. The name of the project is Starship. Because the first baseline of requirements is going to be defined, you add the suffix "BL1" to the project name. When you create the project with the name "Starship_BL1", you need to choose a snapshot view that is configured to work on baseline bl1 (the main branch) as the destination.

When the work for baseline bl1 (the main branch) is finished, and the switchover to baseline bl2 (branch rq_bl2) is going to happen, you need to perform the following steps:

1. Create a snapshot view for baseline bl2 (working on a parallel branch rq_bl2, starting off from the RQ_BL1 label on the main branch).
2. Check out all of the files on the baseline bl2 branch.
3. Remove all checked out files in the RequisitePro project folder on the new snapshot view (otherwise, the RequisitePro Baseline Manager tool will complain about the already existing project)
4. Create a baseline with the RequisitePro Baseline Manager, and store it to a temporary location, as shown in Figure 12.

5. Create a new project from the previously created baseline. The new project has to be located on the snapshot view for baseline bl2.

Important: You must ensure that a different project name but the same location is used (see Figure 13 and Figure 14).

6. If the project has been successfully created, the files are checked in.
7. You can remove any view private files that have been created by the RequisitePro Baseline Manager (mostly XML files).
8. You should remove any remaining checked out files (by undoing the checkout and removing the file name from the folder, using rmname on the cleartool command line), because these entries are referring to files that are no longer part of the RequisitePro project.

Back to top

How to use it

This section will show you how to use these tools.

Comparing RequisitePro documents

When you are working on different branches, one team is working with a version on baseline bl1 (the main branch, as shown in Figure 15) while another team is working with a version on baseline bl2 (the rq_bl2 branch, as shown in Figure 16).

You can easily explore the changes between the two baselines by clicking the first version of interest and selecting Compare, as shown in Figure 17.

Adding and Removing documents

As time goes by, RequisitePro documents will be added or removed to or from the RequisitePro project. The easiest way for you to figure out which documents have been added or removed is to look at the version tree of the RequisitePro project folder, as shown in Figure 18. If different versions exist, there are structural changes between the baselines, as shown in Figure 19.

Comparing the two folders will show the differences (additions and removals of files) in detail.

In case of removed RequisitePro documents, you should carefully consider if it has to be deleted from the other baseline also. If that is the case, it can be removed from the RequisitePro project also. Afterwards, you should remove the file name from the RequisitePro project folder using the rmname command on the cleartool command line.

In case of added documents, there is some extra work you have to do if you want the added documents to become members of the other baseline. Keep in mind that when you import documents, only the requirement text will be imported. The requirement type will be of the RequisitePro document type default requirement type. The requirement attributes will be set to the default values as defined in the requirement type. Any conflicts with already existing requirements can potentially lead to a loss of data.

RequisitePro requirement documents should be added to other baselines by merging them to the corresponding baseline branches. However, the RequisitePro project still does not know about the additional document. The added requirement document needs to be imported by RequisitePro. You can do this by selecting File > Import from the RequisitePro menu.

The file import functionality was originally designed to import .doc files, and to store them later on with a different extension (depending on the document type that you select). Unfortunately, the new file to be imported is already under ClearCase control, and in addition already has the document type-specific extension.

That will lead to a conflict with the file import tool, so a little work around is needed: add a leading character like an underscored "_" to all of the (previously checked out) files that shall be imported. This will keep the already applied extension as a reminder for the document type, and you can easily identify which files you need to remove later on.

After you select File > Import, the Import Wizard dialog box displays, as shown in Figure 20.

The document to be imported can simply be selected by browsing to its location.

Next, specify what kind of information shall be imported, as shown in Figure 21. Choose Document only, because the document already contains RequisitePro bookmarks that are identifying the requirements.

You will need to specify the document type (see Figure 22) and the name of the document. Please ensure that the name does not have the leading underscore "_". It is important that you keep the name of the document. Otherwise. ClearCase considers it a new element instead of a new version of an already existing element.

The import process will detect that the Word document already contains formatting that will potentially be overwritten by the document type formatting. Select Yes to keep the formatting, as shown in Figure 23.

The import process will detect the already existing bookmarks for requirements, as shown in Figure 24. You want to keep the already existing requirement bookmarks, so click No.

The import process will report the requirements that were found, as shown in Figure 25.

When you click the Commit button, the import process finishes and the RequisitePro database updates with the requirements from the already existing bookmarks.

Back to top

Disclaimer

The information, instructions, and procedures presented in this document represent the best of the author's knowledge, and have been tested with RequisitePro V7.0.1, ClearCase V7.01 and Word 2003. You should back up any data source before implementation is started. The instructions and procedures given should be verified on a demo project in order to ensure that the final system fulfils your expectations.

Resources

Learn

• Read the RequisitePro ClearCase Interface users guide and download the supporting script.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
  
• Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
  
• Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• Download trial versions of 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®.
  
  

Discuss

• Join the developerWorks Community in forums, blogs, podcasts, wikis, and more.
  
  
• Requirements Management and RequisitePro forum: Ask questions about Requirements Management and RequisitePro.
  
  

About the authors

Jorg has 10 years of experience in professional software development. He has focused mostly on embedded software systems (vessel automation and automotive) and worked in many different roles, such as software engineer, build- and configuration manager, software integrator and project lead. During this time he's worked with different Rational tools and software development processes. He has gained expertise in how the tooling influences the software development process, what tools are needed in order to support the software development process, and how the software development process needs to be tailored in order to support the team and software projects on a daily basis.

Einar Karlsen has more than twenty years experience in the area of software development tools and methods. He has held positions in research, development, project management, and consulting. His Ph.D. from the University of Bremen addresses the integration of case tools. He has been with the Rational brand for eight years supporting customers in their use of Rational Apex, Rational Suite, and the Rational Software Development Platform.

Rainer Knodlseder is an IT specialist at IBM.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Working in parallel
• Basics
• Implementing
• How to use it
• Disclaimer
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational ClearCase
• Demo: Unified Change Management using ClearCase and ClearQuest
• Briefing: Quality driven software delivery
• Buy: Rational ClearCase

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers