Rational Software Corp.

TOC PREV NEXT INDEX


Working with a Version Control System

This chapter is organized as follows:

Understanding Version Control

Successful team development requires versioning tools that meet certain minimum requirements, including:

Version control systems help make team development possible. At a minimum, they are repositories that store successive versions of files. A version control repository may contain thousands of files, but each version control user typically has a local working area for storing only a copy of the files in the repository that they needs to access.

Types of Version Control Systems

There are two types of version control systems, file-based and view-based. Each type of system has different features and methods for supporting the version control process. Consequently, there are features of each type that are not supported by the other.

File-Based Version Control Systems

Version control systems in this category include Microsoft Visual SourceSafe, Rational ClearCase with snapshot views, Revision Control System (RCS), and Source Code Control System (SCCS ).

File-based version control systems require each user to have a copy of the files in a local folder, and use the file system's read-only attribute to control writing to files.

View-Based Version Control Systems

In view based version control systems, all versions of a file are stored in a versioned file system.

Users do not work with the contents of the versioned file system directly. Instead, they use a work area called a view that provides access to a set of files in the versioned file system. Moreover, a view provides access to an appropriate set of versions of those files by specifying how to choose the version of each file seen in the view.

Rational ClearCase is a view-based version control system.

Version Control Development Concepts

The following concepts are helpful when designing a development process for working with Rational Rose.

Development Activity

A development activity is comprised of changes to several elements. Each activity should encompass a unit of work, such as fixing a bug or defect, or adding a new feature. When changes for an activity are submitted to the repository, the model evolves to a consistent new state.

Integration

Integration is the process of making changes available for use by other developers. Typically, a single person performs the integration activities, but developers can also play this role.

Lineup

A lineup is a collection of specific versions of files from the version control repository. Examples of lineups are:

Lineups represent significant combinations of files. In most development environments, the files that go into any nightly or production build form a lineup. Lineups are also valuable for reproducing specific builds of the system. The term baseline is also used to refer to a formal lineup.

Working in Isolation

It is essential that a developer's work be isolated from the work of other developers. This is important for a number of reasons:

To support these basic team development requirements, developers need to have a private work area for implementing and testing code in accordance with the project's adopted standards, and in relative isolation from other developers.

In addition to providing access to source versions, a work area needs to provide private (isolated) storage for files generated during software development, including:

A work area private storage is typically located within a developer's home directory on a workstation.

Versioning Strategies

Single Stream Versioning

Single stream versioning refers to having a single series of version numbers for each file. In effect, the version history for a file is a linear sequence of revisions.

While developing a project using single stream versioning, each developer always works with the most recent version of files in the repository. To edit a file, a reserved check out is performed on the latest version of the file. After developers make changes, they are submitted. This immediately makes the new version visible to other users, and becomes the latest version for others to base their changes on. This also means that only one person can work on each file at any one time since they must have the most recent version checked out in order to perform work.

Single stream versioning is not ideally suited for fixing defects or bugs for an existing release while doing new development for a future release.

You can use file-based and view-based version control systems for small projects without the need for branching or multiple stream development.

Benefits:

Drawbacks:

Parallel Stream Versioning

Parallel stream versioning permits each file to have a branching tree of versions. This allows many versions of the same file to be active at the same time. Figure 33 shows the version tree for a typical file in a parallel development project.

Figure 33 Parallel Stream Versioning

Most parallel development environments involve nominating a branch in the version control system as the integration branch. The integration branch contains all changes to the project. Testing, release builds, and new development are based on the contents of the integration branch.

All labeled lineups should consist of file versions from the integration branch. Create a labeled lineup as the basis for builds, testing, or further development. You can also create and build a temporary lineup. If the build completes successfully and passes basic sanity tests, you can make the lineup available as a baseline. This process is usually automated, and should be done on a nightly or weekly basis, depending on your team development requirements.

The lineup of file versions in the baseline is used for subsequent development. Development activities should not be performed on the integration branch, but separate from it. When a development activity is finished, the changes for that activity can be merged by an integrator back onto the integration branch. This ensures that the integration branch is strongly controlled and that only correctly working models are used to base further development on.

Benefits:

Drawbacks:

Rational Rose Integration with Version Control Systems

Version Control Add-In

Rational Rose provides version control facilities such as versioning and controlled access to model files by integrating with any SCC1-compliant version control system.

Through its Version Control add-in, Rational Rose makes the most frequently used version control commands directly accessible from its Tools and shortcut menus.

For example, you can use the Version Control add-in to:

Version Control logs its actions in the Rational Rose log window, as well as in the log file that you specify on the Log tab of the Version Control Options dialog box (Tools'> Version Control > Version Control Options).

The Version Control Add-In automatically determines which version control system you installed. To see which version control system and SCC API version the Version Control Add-In uses, see the Version Control Options dialog box.

Note: For the Version Control Add-In to work with your version control system, the version control system has to be configured for your environment.

ClearCase Add-In

The ClearCase Add-In provides a tight integration between Rational Rose and Rational ClearCase. In addition to the generic commands that the Version Control Add-In provides, the ClearCase Add-In provides:

Note: For the ClearCase Add-In to work with ClearCase, ClearCase has to be appropriately configured for your environment.

Choosing and Activating a Version Control Add-In

When you install Rational Rose, the installation program detects whether ClearCase or an SCC-compliant version control system is installed on your system. Based on the version control system you installed, either the Version Control Add-in or the ClearCase Add-In is activated on your system.

If you install or change your version control system after you install Rational Rose, you must ensure that the appropriate add-in is activated. In addition, ensure that only one of the version control add-ins is active at a time. Because the Version Control and ClearCase add-ins use many of the same commands, you may receive error messages or unpredictable results if both are activated.

To activate or deactivate a version control add-in, click Add-In Manager on the Add-Ins menu, and click the add-in you want to activate or deactivate.

Note: If you use Rational ClearCase for version control, we recommend that you activate the ClearCase Add-In, even though you can also use the Version Control Add-In in the Windows NT or Windows 2000 environment. The ClearCase Add-In provides a much tighter integration and provides you with direct access to many ClearCase commands from within Rational Rose.

Using Rational ClearCase

About ClearCase

ClearCase is a comprehensive software configuration management system. It manages multiple variants of evolving systems, tracks which versions were used in software builds, performs builds of individual programs or entire releases according to user-defined version specifications, and enforces site-specific development policies.

These capabilities enable ClearCase to address the critical requirements of organizations that produce and release software, namely:

At its core, ClearCase has a secure data repository. It contains data that is shared by all users and includes current and historical versions of source files, along with derived objects built from the sources by compilers, linkers, etc.

In addition, the repository stores detailed accounting data on the development process itself, such as who created a particular version, what versions of source went into a particular build, and other relevant information.

Conceptually, the data repository is a globally accessible, central resource. The implementation, however, is modular. Each source (sub)tree can be a separate versioned object base (VOB). VOBs can be distributed throughout a local area network, accessed independently, or linked into single logical tree.

Versioned Object Bases (VOBs)

ClearCase development data is organized into any number of versioned object bases (VOBs). Each VOB provides permanent storage for all the historical versions of all the source objects in a particular tree -- the right versions of the development objects appear, and all other versions are hidden.

A version-controlled object in a VOB is called an element. Its versions are organized into a version tree structure with branches and subbranches.

Figure 34 Version Controlled Object (VOB) Tree Structure

Figure 34 shows branches that have user-defined names to indicate their role in the development process. All versions have integer ID numbers. You can assign version labels to important versions to indicate development milestones, such as a product release.

ClearCase Views

Users access the ClearCase repository through views. A view is an isolated virtual work area that provides dynamic access to the entire data repository. The changes being made to a source file in a particular view are invisible to other views. Software builds performed in a view do not disturb the work taking place in other views.

Working in views, ClearCase users access version-controlled data using standard path names and their accustomed commands and programs. The view accesses the appropriate data automatically and transparently.

A view's isolation does not render it inaccessible. A view can be accessed from any host in the local area network. A view can be shared by several users working on a single host or on multiple hosts.

Configuring ClearCase for Rational Rose

By using a view model combined with a virtual file system, ClearCase allows users to specify the lineup of file versions with which they want to work. (A configuration specification, or config spec, controls the lineup used for a particular view.) Rational Rose can see the files in the current view as if they were stored on a regular (non-ClearCase) file system.

Rational Rose specifies the set of files that make up the model, and ClearCase provides the versions of these files based on the view's config spec. A config spec is a set of rules that determines which files are in a view.

To add files to version control, save the model to a view directory that is not view-private.

ClearCase allows you define a new element type, including specifying the merge and differencing tool that should be used on files of the new type. Rational Rose uses this feature to define an element type that applies to all Rational Rose files under version control. With this element type defined, all new Rational Rose files placed into a VOB are associated with the file type, and use Model Integrator as their default merge and differencing tool. (For more information about Model Integrator, see Chapter 5.)

Steps for Setup

To configure your ClearCase environment to work with Rational Rose:

1 Create and mount a ClearCase VOB (for example, ProjectRose).

    Note: Create VOBs and views directly in ClearCase (outside of Rational Rose).

2 Create a ClearCase view to provide access to the VOB you created. If you use ClearCase on Windows, you must map the view to an appropriate Windows NT or Windows 2000 drive (for example, z:\)

3 Create all necessary views, prepare the model for team development, and organize the model in to controlled units.

4 To create the rose_unit element type in the VOB(s) where you store model files, do one of the following:

    If you are using Rational Rose in the Windows NT or Windows 2000 environment:

    cleartool mkeltype -supertype text_file -manager _rose -c "Model files" rose_unit

    If you use Rational Rose in a Unix environment:

    In Rational Rose, click Tools > ClearCase > Setup VOB for Rose Units to add the rose_unit element type and type manager to the VOB.

Using Microsoft Visual SourceSafe

Microsoft Visual SourceSafe (VSS) stores and retrieves files on your local disk. Each VSS project has a working folder specified for it. Rational Rose saves model elements to, and loads elements from this working folder. VSS then checks those local files in to and out of its repository.

Configuring Microsoft Visual SourceSafe for Rational Rose

Steps for Setup

1 Ensure that there is a Microsoft Visual SourceSafe database available to store the model. Create the database directly in Visual SourceSafe.

2 Since the Version Control Add-In uses the current user name to identify the SourceSafe user, the system administrator must add you as a user before you can use the integration. To identify the current user name, click Version Control on the Tools menu in Rational Rose, and click Version Control Options.

3 In Microsoft Visual SourceSafe, open the database where you want to store the model and create a project for the model. (You can start Visual SourceSafe from within Rational Rose by clicking Version Control on the Tools menu in Rational Rose, and then click Start Version Control Explorer.)

4 Right-click the project and click Set Working Folder. Select an existing working folder where you want to version control your model or create a new folder.

    Note: If you attempt to control two files of the same name in the same Visual SourceSafe project, but you specify different working folders for the files (for example, c:\NewPackage.cat and c:\temp\ NewPackage.cat), Visual SourceSafe controls the first file in the project (c:\ NewPackage.cat); it does not control the second file (c:\temp\ NewPackage.cat). No error message informs you that the second file was not controlled. Consequently, we strongly recommend that you save all the files from a single project in the same working folder. Otherwise, you may think you have controlled a file, when you actually have not done so.

5 Click Options from the Tools menu. On the Command Line Options tab, select the Assume Project Based on Working Folder check box.

Note: If the Version Control commands on the Tools menu in Rational Rose do not work, the SourceSafe Integration component in Visual SourceSafe may not be installed. To install that component, start the Microsoft Visual SourceSafe setup program. Click Add/Remove and select Enable SourceSafe Integration on the Maintenance Mode page.

Using Version Control Features From Rational Rose

Using the Version Control Add-In on a Previously Controlled Model

If a model is currently under version control, but not through the Version Control Add-In, you must add the controlled units to version control by using the Add to Version Control command. If you do not add the model using this method, the Version Control Add-In will be unaware of any of the previously controlled units. for that model.

Note: This information applies only to the Version Control Add-In. If you use the ClearCase Add-In, you do not have to do anything because it will be aware of any previously controlled units.

Follow these steps to prepare a previously controlled model for use with the Version Control Add-In:

1 Ensure that the model is not currently open in Rational Rose.

2 In your version control system, check out all the controlled units that belong to the model. (This cannot be done through the Version Control Add-In because it does not know that the model is under version control.)

3 In Rational Rose, open the model, load all units, and click Add to Version Control on the Tools menu's Version Control menu.

4 If you want to check-in the files after this operation, clear Keep Checked Out.

5 If you use Microsoft Visual SourceSafe, click Browse, search for the project, then click OK. If all files are located in the same project, click Select All, then click OK. Otherwise, click the check box next to each file located in the selected project, click OK, and then repeat steps 3-5 for each set of files located in a different project.

The model is already under version control, so the Version Control Add-In only updates the controlled units with some additional Version Control information. Now, you can use the Version Control commands to check out and check in the units.

Adding Controlled Units to Version Control

The following procedure describes how to save a package to a file, and how to control it in ClearCase or an SCC-compliant version control system such as Microsoft Visual SourceSafe. You can use the same procedure to control the model file, the deployment diagram, or the model properties.

1 Ensure that the unit that the package belongs - that is, the model file or the enclosing package - is checked out.

2 Right-click the package in the browser or the diagram, then click Add to Version Control.

3 A list shows all model elements that can be added to version control. The specified packages are selected by default in the list. Ensure that you select all packages to add to version control from this list.

4 If you use Microsoft Visual SourceSafe, ensure that the SourceSafe Project box refers to the project that represents the working folder where the selected file units are (or will be) located. If the box does not refer to the appropriate project, click Browse and select the appropriate project.

    Note: We recommend that you create new projects in the dialog box displayed when clicking Browse. However, if you do, the working folder for the new project becomes the same as the folder where you save the controlled units you are adding to version control.

5 To keep the files checked in after this operation, clear the Keep Checked Out check box.

6 You can also write a comment in the Comment box. Your version control system inserts the comment as a description of the new unit. This step is optional.

7 You can also click Advanced to display a dialog box with additional options. This step is optional.

    This button is not available for all version control systems.

8 Click OK.

9 For each selected unit not yet saved to a file, a Save As dialog box displays. Specify the name and storage location of the new unit (for example, x:\ordersystem\units\user_serv.cat). You must save the file in the appropriate working folder in Visual SourceSafe or in the appropriate ClearCase view.

10 Click Save.

Rational Rose creates a file unit from each selected package, if needed, and adds each file to the version control system.

Note: If you use Microsoft Visual SourceSafe, the Add to Version Control command can only handle files located in the same Visual SourceSafe project and working folder. To add files that belong to different projects, you must repeat the Add to Version Control command for each project.

Checking in Controlled Units

To check in a loaded controlled unit into ClearCase or an SCC-compliant version control system, such as Microsoft Visual SourceSafe, use the following steps:

1 Right-click the unit in the browser or the diagram, and click Check In.

    A list with all loaded, checked out controlled units in the current model displays. Any units currently selected in the browser or in a diagram are selected by default in the list.

2 Select the appropriate units.

3 Optionally, write an explanation of the check-in in the Comment box. The text you type is stored by your version control system as history for the current check-in.

4 Optionally, click Advanced to display a dialog box with additional options.

    For example, to check in an unchanged unit in ClearCase, select the Check in even if identical option in the Advanced dialog box. If you do not select this option when checking in an unchanged unit, you receive an error message. (The Advanced button is not available for all version control systems.)

5 Click OK.

    Rational Rose checks in the units and makes the corresponding model elements read-only in the model.

Note: If you use the Version Control add-in, to be able to check in a controlled unit from within Rational Rose, the unit must have been previously added to version control from within Rational Rose using the Add to Version Control command. This restriction does not apply to the ClearCase add-in.

If you use the Version Control Add-In with Microsoft Visual SourceSafe, the Check In command can only handle files located in the same Visual SourceSafe project and working folder. To check in files that belong to different projects, you must repeat the Check n command for each project.

Checking Out Controlled Units

To check out a loaded controlled unit from ClearCase or an SCC-compliant version control system, use the following steps:

1 Right-click the unit in the browser or the diagram and click Check Out. A list with all loaded, checked in controlled units in the current model displays. Any units currently selected in the browser or the diagram are selected by default in the list.

2 Select the units you want to check out.

3 Optionally, write an explanation of the checkout in the Comment box. The text you type is stored by your version control system as history for the current check-out.

4 Optionally, click Advanced to display a dialog box with additional options.

    For example, if you use ClearCase, you can make an unreserved check out with the advanced options. (The Advanced button is not available for all version control systems.)

5 Click OK.

    Rational Rose checks out the files and makes the contained model elements editable.

6 If Rational Rose prompts you to load the unit, click Yes.

Note: If you use Microsoft Visual SourceSafe, the Check Out command can only handle files that are located in the same Visual SourceSafe project and working folder. To check out files that belong to different projects, you must repeat the Check  Out command for each project.

To check out a controlled unit, the unit must have been previously added to version control from within Rational Rose using the Add to Version Control command.

Undoing the Check-Out of Controlled Units

To undo the check-out of a loaded controlled unit and to load the latest checked-in version:

1 Click Version Control on the Tools menu, and then click Undo Check Out.

    A list with all loaded, checked-out controlled units in the current model displays. Any packages currently selected in the active diagram are selected by default in the list.

2 Select the checked-out unit.

3 Optionally, click Advanced to display a dialog box with additional options. This button is not available for all version control systems.

4 Click OK.

5 If Rational Rose prompts you to save the changes before loading a new unit, click No.

Note: If you use Microsoft Visual SourceSafe, the Undo Check Out command can only handle files located in the same Visual SourceSafe project and working folder. To undo the check-out of files that belong to different projects, you must repeat the Undo Check Out command for each project.

Getting the Latest Version of Controlled Units

To copy the latest checked-in version of a loaded controlled unit to your Microsoft Visual SourceSafe working folder, or dynamically access it via the ClearCase view to load that version into the model, follow these steps:

1 Click Version Control on the Tools menu, and then click Get Latest.

    A list with all loaded, checked-in controlled units in the current model displays. Any packages currently selected in the active diagram are selected by default in the list.

2 Select the appropriate unit.

3 Optionally, click Advanced to display a dialog box with additional options. This button is not available for all version control systems.

4 Click Get.

5 If Rational Rose prompts you to save the changes before loading a new unit, click No.

Note: If you use Microsoft Visual SourceSafe, the Get Latest command can only handle files that are located in the same Visual SourceSafe project and working folder. To get the latest versions of files that belong to different projects, you must repeat the Get Latest command for each project.

If you use Rational ClearCase, the Get Latest command is only valid for snapshot views. See your ClearCase documentation for more information on views.

Removing Controlled Units from Version Control

To remove a loaded controlled unit from version control, follow these steps:

1 Ensure that the unit to which the unit belongs - that is, the model file or the enclosing package - is checked in.

2 Click Version Control on the Tools menu, and select Remove From Version Control.

    A list shows all loaded controlled units under version control by the Version Control Add-In. Any packages currently selected in the active diagram are selected by default in the list.

3 Select the unit that you want to remove.

4 Optionally, click Advanced to display a dialog box with additional options. This button is not available for all version control systems.

5 Click OK. The selected unit is removed from version control and its contents are incorporated into the model, but will continue to exist as:

Note: If you use Microsoft Visual SourceSafe, the Remove From Version Control command can only handle files that are located in the same Visual SourceSafe project and working folder. To remove files that belong to different projects, you must repeat the command for each project.

Note: To remove a controlled unit from version control from within Rational Rose, the unit must have been added to version control from within Rational Rose, by using the Add to Version Control command.

 1

  1. SCC (Source Code Control) is the Microsoft standard API for version control systems.

Rational Software Corporation  http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX