TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Summit Configuration Manager (Apex/Summit)

This chapter discusses the concepts of version control and configuration management used in Apex/Summit. Please see the ClearCase User's Guide for information on version control and configuration management using ClearCase.

This chapter includes the following topics:

Additional information on version control is available in the Command Reference.


The Problem

For any software system that is more than a few lines of code, managing multiple versions and multiple developers is a challenge.

Managing Multiple Versions

As a software system evolves, a change history is usually kept for each of the project's significant files (source code modules, executables, documents, databases, tests, and so on) as well as for each significant configuration of those files. Keeping a change history provides a way to measure progress as well as a way to access earlier baselines.

However, tracking the evolution of files and configurations through time adds yet another dimension to the project's complexity. The project must manage:

The more files a project accumulates, the more versions and configurations there are to manage, and the more time-consuming and difficult the management tasks become.

Managing Multiple-Person Projects

Dividing the development work among several people shortens the overall schedule only if these people can work in parallel. To do this, each developer needs to be able to implement and test his or her own piece of the system without being held up by anyone else's activities.

Parallelism is difficult to achieve on a complex project. When numerous dependencies exist among software modules, it is difficult to identify sets of modules that are suitable for assignment to independent teams. When dependencies exist across developer boundaries, changes made by one developer render the modules of dependent developers out of date. Such dependencies also cause changes made by one developer to delay the activities of dependent developers while they recompile their modules against the changed ones.

Similar issues arise for people developing ancillary products such as documentation and tests, which are logically dependent on the software. Changes made to the software lengthen the schedules for these products or render them obsolete.

Not surprisingly, effective management becomes critical for communicating, coordinating, and integrating the efforts of multiple interdependent people.


Configuration Management and Version Control (Summit/CM)

Summit/CM provides support through development, release, and maintenance of software projects and consists of two components: configuration management and version control. Version control controls changes to individual files in each subsystem. It also tracks what changes were made, when, why, and by whom. Configuration management aids in constructing, releasing, and maintaining multiple consistent sets of versions in each subsystem.


Version Control

Once a software project has started, it is a good idea to place the files under version control. Version control requires a special command to be executed before a file can be modified. Then, while a file is being modified by one developer, another developer cannot generally change it. Apex version control gives the developer control over this change process. The version control mechanisms track file changes, coordinate access to shared files, coordinate the work of multiple developers, and propagate changes. In general, each file in a view may be placed under version control. When a file is controlled, it must be checked out to be modified. Checking out a file reserves it for editing. When the file is updated and tested, it is checked in, making it available to other users.

The Check-In and Check-Out System

Apex divides programming efforts into subsystems to make them more manageable. As stated previously, a specific version of a subsystem is called a view. A view contains the files that represent the logical elements in a subsystem. Rational subsystems contain views. Every view must be in a subsystem. Because views contain actual files, they are directories in which compilation is performed.

Summit/CM is a system for controlling modifications made to individual files in a subsystem. Files under the control of Summit/CM can be checked out and checked in, much like books in a library.

When a user checks out a file with a reservation, the user has sole access to the file until is checked back in. Only when a file has been checked back in can another user check it out.

Controlled and Uncontrolled Files

Files in views must be explicitly placed under Summit/CM control for Apex to track changes in them and control access to them. Only files in views can be placed under Summit/CM control. When a file is placed under Summit/CM control, the following events occur:

Propagation of Changes Between Views

Consider two files named requirements in an example of a subsystem. One file named requirements is in the dev.wrk view, and another file named requirements is in the test.wrk view. Each requirements file corresponds to the same Summit/CM element. However, the two files named requirements might be different versions of the same element. When a subsystem contains more than one view, as in the preceding example, files representing the same element in different views can have different contents because they represent different versions of the element.

For example, suppose a developer creates new versions of several files in a view by checking out the files. When the changes are complete, the developer checks the files back in. It is then possible to copy each changed file to a different view by executing the Control > Update Objects menu command. When Control > Update Objects is invoked to update a controlled file from one view into the corresponding element in another view, the destination file is changed to match the source file. After a Control > Update Objects command is executed, the files in the source and destination views are the same in content and version number.

To illustrate how this works, suppose that in the preceding example, a developer creates new versions of several files in dev.wrk by checking out the files, updating and testing the files, and checking the files in. The developer can then move the changed files individually to the test.wrk view by executing Control > Update Objects. Control > Update Objects changes the files in the destination view (test.wrk) to match the changed files in source (dev.wrk) view.

The Control > Update commands automatically change out-of-date versions in a destination view to newer versions.

Apex Projects

When a number of developers are working on a project, things can be set up in Apex to make the developers more productive and make some of their tasks easier.

When there are a number of subsystems and views, just entering their names can be tedious and time consuming. If there are conventions concerning models or histories, these may be difficult to remember because they are not used all that often. A project allows access to files, directories, and resources named in the project by clicking special icons instead of typing pathnames.

Apex provides the ability to create a file called a project that contains this kind of information and makes it available at various points in the Apex user interface. Projects can be created on a per-user basis or shared among groups. Once created, projects must be activated to be used in an Apex session.


The Summit/CM Database

The Summit/CM database is central to Apex version Apex maintains a Summit/CM database that tracks a file's development by recording the changes made to each controlled file. Each time a file is checked in, a new version of the file is created in the Summit/CM database. In this way, the Summit/CM database provides each developer with access to the same set of files, even though each file may be under a different stage of development.

The Summit/CM database contains much more information than is saved normally within a library by other development environments. The database saves all versions of each controlled file and provides locking to prevent simultaneous check out. Summit/CM also keeps the Ada program library consistent. This aggregate of information within the Summit/CM database is the reason it is possible —— and even easy —— to have multiple releases, and to revert to previous configurations.

Version Histories and Version History Families

When files are checked out, modified, and checked in repeatedly, the result is a time-ordered, numbered sequence of versions, called a version history. The Summit/CM database maintains version histories by recording all changes made to every controlled file.

Because each version of a file represents a snapshot of the file at some moment in time, the Summit/CM database can be used to see any version in a file's version history.

For example, File A in the following illustration has three versions, each one containing an image of the file as it appeared at the time it was checked in. The version history for file A is illustrated in Figure 8.

Figure 8 Version History

In this manual, a version of a file is represented by the file name followed by the version number in parenthesis. The third version of file A is represented as A(3).

Version histories of controlled files can be grouped together into version history families. For example, the version histories of a subsystem's files can be grouped into a version history family.

Version History Families

A version history family is a set of version histories. A version history family includes at most one version history for each file in the subsystem. A version history family composed of the version histories of three files is illustrated in Figure 9. Version history families can be used to group together version histories that are related in some way. Each file under Summit/CM control is a member of a named version history family. Version history families are properties of subsystems.

Figure 9 Version History Family

In a version history family, a view is created for each variant of a subsystem. Files that have different contents for each variant are placed in different version history families. By specifying three items, the element's version history family name, the file name, and the version number, a file can be fully identified in the Summit/CM database. In a simple software-development project, the existence of version history families can be ignored. Apex then regards all files in the project as being in the same version history family.

Uses of Version History Families

An example of using different version history families is illustrated in Figure 10 . If in subsystem SS, view A and view B both contain version 2 of file W from the Common version history family, view A and B contain the same file. However, if view C contains version 2 of the file W from the Special version history family, it is not the same file.

Figure 10 Version History Families Example

Each subsystem contains a Summit/CM database that contains information on the files that are controlled in that subsystem. This means each view in a subsystem uses the same database.

In this manual, the Common version history family illustrated in Figure 10 is depicted as illustrated in Figure 11. "A 1 2 3" is the version history of file A. Note there is no requirement to have the same number of versions for each file. Also, all versions of files (that have been saved) are contained within the database. A working view can be created using any combination of versions contained within the database. Version 2 of file A is simplified to A (2). Version 2 of file A from the Common version history family is simplified to A (Common-2).

Figure 11 Version History Family Representation in this Manual

Version history families can be useful in the following situations:

Each view is an alternative specification or implementation of the subsystem. Each view contains at most one version of each file in the subsystem. Figure 12 illustrates the latest.wrk working view composed of the latest versions of all files and the older.wrk working view which consists of older versions of the files.

Figure 12 Sample Views in the Same Subsystem

Configuration Files

A configuration is a text file that provides a way to group together views from different subsystems. For example, to construct a system release, a configuration that includes release views from each of the system's component subsystems can be created.

Configurations are used to represent the import information during compiling. They are also used to specify the closure when main programs are to be linked. Most commands accept a configuration file as the argument.

The contents of a configuration are either the fully qualified names of views or the fully qualified names of other configurations. When a configuration file contains a configuration, all the views in each configuration are included.

A configuration contains files from at most one view in each subsystem. Configurations can be used to identify releases within a system. Configurations are illustrated in Figure 13.

Figure 13 Sample Configurations Consisting of Two Views

This example defines two configuration files: s contains views 1a and 2a and t contains views 1a and 2b. There is no limit on the number of configuration files that can contain a specific view. Each subsystem and view is a directory of files. Views are logically subdirectories within their subsystem directory.

Corresponding Files

A subsystem usually contains at least one working view. A working view is a view in which files can be checked out, modified, checked in, compiled, and tested.

At any given time, each working view contains exactly one version of each file —— usually (but not necessarily) the latest version. Files are said to be corresponding if they exist in different views of the same subsystem and have the same view-relative name. Corresponding files may or may not share the same version history.

When corresponding files have the same version history, a file can be checked out for editing in only one view at any given time. If a file is checked out in one view, the corresponding object in another view cannot be checked out until the file in the first view is checked in.

Even after a user has checked in a file, corresponding objects in other views are not affected by changes the user has made in the file until the user explicitly updates from the first view using the Control > Update Objects command and the Accept latest version of each object option.

When corresponding files do not share the same version history, they can be checked out in different views at the same time, and changes made in one view will never affect other views. The differences are illustrated in Figure 14.

Figure 14 Corresponding and Non-Corresponding Files

File A in view corr.wrk and file A in view corr2.wrk are corresponding objects. If the file A in view corr.wrk is checked out with a reservation, the file A in view corr2.wrk cannot be checked out with a reservation, and vice versa. The file A in view not_corr.wrk corresponds with the other two file A's. The file A in not_corr.wrk can be checked out regardless of the status of the other two file A's. The file A(2) in the corr2.wrk view is not the same file as A(2) in the not_corr.wrk view.


Checking Files Out and In

When a file is controlled, it must be checked out before it can be modified. When a controlled file has been checked out by a user, it can be edited in any way, but all other users are locked out —— they cannot modify the file until it has been checked in again.

When a controlled file is checked in, it is unlocked and is again available to other users, provided they have the necessary UNIX user privileges to check it out.

The process of checking a file out and checking it back in is illustrated in Figure 15.

Figure 15 Checking Out and In a File

Checking Out a File

When a file is first placed under Summit/CM control, it is not modifiable. To make a controlled file modifiable, it must be checked out using the Control > Check Out command.

The Check Out operation checks out files for modification either with a reservation or privately. The default is check out with a reservation. When a file is checked out privately, no reservation is acquired.

Check Out with a Reservation

Checking out a file with a reservation from the Summit/CM database has these effects:

When a file has been checked out, the user can make changes to it (including compiling, linking, and debugging), save it, and make more changes. None of these changes are reflected by the Summit/CM database until the user checks the file in.

Private Check Out

A private check out does not obtain an exclusive reservation of the version history of the file. A private check out allows modification of the file in the current view; however, a private check out may not be checked in unless the private check out is upgraded to a check out with a reservation. A file may be privately checked out even if its history is already reserved.

A private check out is one way in which Apex supports simultaneous development by multiple users by allowing other users to work on files that are already checked out. It also allows one user to test a temporary change while another user has the file checked out.

Checking out a file privately from the Summit/CM database has these effects:

Checking In a File

To check a file in, the Control > Check In command is used. Checking a file in has these effects:

Each time a file is checked out, modified, and checked in, a new version of the file is added to the Summit/CM database. This sequence of versions is called a version history.

To check in a file that has been checked out privately, the file may need to be merged with the version that was checked out with a reservation or the file may need to be upgraded to be checked out with a reservation.


Version Control Commands

The version control commands allow the user to:

The first six of these commands are discussed in the following sections.

Note: All the examples assume an access category of group_public.

Control

The control operation places a file under version control. The file must be in a view. Version one of the file is created. For example, consider if the control operation is used to control unit U using the Common version history family (VHF). This example using the default access control (see Access Control (Apex/Summit)) of group_public is illustrated in Figure 16.

Figure 16 Control Operation Illustration

Control > Check Out

Before a controlled file may be modified, it must be checked out with a reservation or privately. A Control > Check Out command with a reservation operates as illustrated in Figure 17.

Figure 17 Control > Check Out with Reservations Command Illustration

Private Check Out

A private check out does not obtain an exclusive reservation of the version history of the file. It is typically used when a file is already checked out, but a new change is critically needed. This is illustrated in Figure 18.

Figure 18 Control > Check Out Privately Command Illustration

Private Check Out Processing

To make an emergency change to an already checked out file to satisfy a critical need:

1 . Check out the file privately.

2 . Make the required changes.

3 . If your version of the file is the latest because the check out with reservation has been abandoned, check in the file.

4 . Otherwise:

a . Wait for the file to be checked in.

b . When the file is checked in, if there are no conflicts with your changes, check in the file.

c . Otherwise:

i Merge the new version with your private version using the Control > Merge command.

5 . Check in the updated file.

The Control > Check In command checks in the designated files. This causes a new version of the file to be completed. The history of the file is no longer reserved. This is illustrated in Figure 19.

Figure 19 Control > Check In Command Illustration

Control > Update Objects

These commands update a set of destination files. They play a central role in propagating changes to other views. They support integration by respecting the version control relationships:

A file will be updated only to a newer version; an older version will not moved into a view. Only files that have the same view-relative name (the basename, not the full pathname) are considered for update. The static version control relationships are based on the histories of files in the version control architecture. There are options that override the standard operation for special purposes.

Each destination argument may name a file, a directory, or a view. When a file is specified, the file is updated to a later version. When a view or directory is specified, the operation is applied recursively to update all nested files and to create any files that are present in the source but not in the destination (subject to the options).

An example of the Control > Update Views command using the defaults is illustrated in Figure 20. The following changes are made in view 1b:

Figure 20 Update View Command Illustration


Configuration Management

Configuration management for a system involves tracking all the subsystems into which the system has been decomposed. Subsystems represent the system components and enforce the intercomponent interfaces as specified by the system architecture. Configuration management also tracks all the views of each subsystem. Multiple views support parallel development, multi-target development, and release views.

Parallel Development

Apex permits parallel development within subsystems as well as between subsystems. A subsystem can be assigned to an individual developer or to a team of developers, depending on its size. When a development team is working on the files in a subsystem, separate working views can be created for individual members of the team.

Typically, corresponding files in all the working views share the same version history. When that is the case, development can proceed without conflict because each file can be checked out in only one view at a time, and individuals can update from other views at their convenience.

Multitarget Development

Multiple working views can also be created to support parallel development of different variations of a product. The most common example of an environment that makes use of multiple working views is a multiple target development. Typically, such an environment has these characteristics:

For example, there might be version history families for Common, Sun4, and Rs6000 development. The Common history family would group together the history for files that are target independent, while the Sun4 and RS6000 families would be used to group together the history of all the files that are being developed for those particular targets. The chapter on Establishing a Development Process (Apex/Summit) presents more information on the multitarget development.

Development and Release

Throughout the software life cycle, there will be new versions of the software to incorporate into the system in a timely manner. The freeze-release method is used to develop and release updates. This method is best illustrated with an example. The example software is broken up into three subsystems as illustrated in Figure 21.

Figure 21 Example System with Three Subsystems

Each developer begins with an initial version of the subsystem's implementation. When the developer of a subsystem feels comfortable the implementation is ready for other developers to use in testing their subsystems, the developer freezes and releases his/her work. He/she then copies the release view to his/her working view and continues developing. If subsystem B has been released three times, the subsystem B environment might be as illustrated in Figure 22.

Figure 22 Environment for Subsystem B

Freezing and releasing a subsystem automatically generates a new working copy of the subsystem implementation, which the team then uses to continue its work.

Figure 23 illustrates how this develop-freeze-release-copy-develop process continues in parallel. The subsystem A developer has made three releases, while the subsystem B developer has made five releases, and the subsystem C developer has made two. But each of the frozen releases is available for testing and use by other team members.

Figure 23 Each Subsystem has an Independent Release Schedule

Additional information can be found in Integrating and Releasing Systems in the Programming in Apex.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS