GENERIC

SOFTWARE CONFIGURATION MANAGEMENT DOCUMENT

@(#)scm.htm 3.6 - 04/14/05

Permission is granted to reproduce and adapt this document provided credit is given to the University of West Florida. This documentation is provided "as is" and no warranty of fitness for any particular purpose is made or implied.

ABSTRACT

This document describes the Software Configuration Management (SCM) concepts and policies to be followed by team members using the GUMP++ software development and maintenance process. It also describes in greater detail the responsibilities of the SCM group.

TABLE OF CONTENTS

LIST OF FIGURES

LIST OF TABLES

Table 1. SCM Controlled Directories
Table 2. Correct Umask Settings
Table 3. Tisk Directory Naming Conventions

1.0 INTRODUCTION

The development, maintenance and distribution of a software product requires a large number of files: source files, documentation files, executables, web pages, test scripts, test data, and numerous information files to track bugs, record inspections, document test cases, etc.

The purpose of Software Configuration Management (SCM) within GUMP++ is to help the project team keep control of all these files so that they can locate them as needed and to avoid interference between the actions of different team members (the simultaneous update problem). All project team members need to be familiar with SCM concepts and policies. However GUMP++ also provides for a specific SCM group with defined responsibilities to manage the complexities of group access to the files and help avoid chaos.

This document describes the general SCM concepts and policies that have been found to be valuable within GUMP++, as well as the responsibilities of the SCM group. However GUMP++ has been used on several different products, including recon2, recon3 and GUMP itself [See Note 2]. There are numerous product-specific details, such as file names, build procedures, development platforms, etc. which change frequently. To allow for easy change, these specifics are described in an SCM Specifics document for each project, which is kept in the how_to_notes directory. The present document should be read in conjunction with the SCM Specifics document for the specific product(s) with which the reader will be working.

Note 1: An important responsibility of the SCM group is to update the SCMSpecifics documents to reflect the current procedures being followed for each product, and specifically to be sure that these procedures are completely clear and up-to-date for the following project team.

All GUMP++ project team members are assumed to be familiar with the basic concepts of configuration management, as described, for example, in Software Configuration Management, by Wayne Babich. Since the development platform for GUMP++ projects is usually Unix, they should also be familiar with Unix file security, groups, etc.

The SCM group must be familiar with the details of the version control tool (currently sccs) to be used and should know how to read and write simple Unix scripts that are used to facilitate many SCM functions. The remainder of this document assumes its readers have received the appropriate training for their role.

Note 2: Although GUMP++ is mentioned in this document as one of the "products" being maintained, the procedures followed to modify GUMP++ are specified in the SEPG Document and are NOT the same as the GUMP++ process itself. However the GUMP++ baseline files are kept under configuration management control by the SCM group following the procedures for check-out and check-in described in this document.

2.0 GENERAL CONCEPTS AND POLICIES

2.1 DEVELOPMENT PLATFORMS, BACKUP AND RECOVERY

Experience has shown that system hardware and software failures are frequent. An effective practice has been to designate a primary development platform and a backup development platform for the GUMP++ team. The goal is to be able to recover from a failure on the primary development platform by transferring GUMP++ activities to the backup development platform with a loss of at most one week's work.

Each platform consists of one or more networked multi-user computers possessing the file space, directory structure, compilers (C, Tcl, ...) and other development tools (atac, ...) used by the GUMP++ team. All team members need to have accounts pre-created on both platforms and must have these accounts configured (e.g. the .cshrc and .login files) so that they can perform their jobs.

The SCM group shall make weekly backups of all the controlled directories from the primary development platform to the backup development platform.

GUMP++ team members normally perform much of their work in their own directories which are not controlled by SCM. Each team member is responsible for performing a weekly backup of all such work files.

The SCM group shall perform a trial recovery on the backup platform sometime early in the semester to confirm that the backup and recovery system is fully functional for all users.

2.2 FILES AND DIRECTORIES

For each product we may distinguish two sets of files:

1. Controlled Directories: These include all the files used in the development and maintenance of the product that are shared by the project team. Examples include the working files in the TISK directories, test sets and scripts in the IVV directories, GUMP++ forms in the forms directory, etc. These files are the primary responsibility of the team members who are using them. The SCM group's responsibility is limited to backup and recovery when necessary.
2. Product Baseline: This is a subset of the controlled directories that includes the key files which should not be modified without going through a change control procedure. Examples include source code, user documentation, and web pages. These files are kept under tight control of the SCM group, using a version control tool (currently sccs).

The controlled directories are all located under one top-level directory on the primary development platform. For example as of April, 2000 the primary development platform was the cslab.uwf.edu computers on the Pensacola Campus and the top-level-directory was /usr/cs/CEN6015FWB/recon. Appendix A is an extract from the directory structure. Note that platforms and directories often change so these directory names are just examples.

Table 1 describes some of the controlled directories used.

Table 1 - SCM Controlled Directories

2.3 FILE PROTECTIONS

As a TISK progresses, GUMP++ team members normally exchange documents, source code, etc. by placing files in the appropriate controlled directory and then informing other team members of their presence. Other team members always look in the controlled directories to get the latest information on any topic. Files in the controlled directories thus need to be readable by all GUMP team members.

The minimum requirement for all files placed in the controlled directories is read-write for the user (i.e the owner) as well as read for the group. If the file placed in the controlled directory requires modification by other members of the team then that file must also have group write permission.

All GUMP++ team members need to be sure that the system administrator has set their primary group as the group dedicated to the project. This check should be performed as early as possible in the semester. Otherwise a team member may inadvertently make a file or directory unreadable to his/her co-workers. It is also desirable for each team member to set their "umask" which determines the default permissions that will apply when the team member creates a file. An appropriate value for umask will avoid accidental file permission problems for the team. Each team member should place one of the umask commands found in Table 2 in their ".login" or their ".cshrc" file.

Table 2 - Correct Umask Settings

2.4 FILE NAMING CONVENTIONS FOR SELECTED DIRECTORIES

All GUMP++ team members should follow the file naming conventions described here as closely as possible, though there may occasionally be slight differences due to the nature of a particular product or TISK.

Note: In the past, naming conventions have varied considerably. GUMP++ team members should thus follow the conventions listed in this document, and not simply duplicate what they find from earlier TISKS.

2.4.1 Deficiency Reports

All DRs should be located in the DR directory. Each DR is a separate text file named DR### (e.g., DR001 for deficiency report 1).

2.4.2 IV&V Directories and Reports

IVV test cases and the IVV regression test set should be located in the IVV directory; the exact organization may be determined by the IVV group.

Note that all IVV forms that report on results for a specific TISK will be maintained in the TISK directory as described below.

2.4.3 SCM Directories and Files

The SCM directory contains files and scripts used by the SCM group.

2.4.4 SQA Directories and Files

The SQA directory contains files used by the SQA group.

2.4.5 How_to_notes Directory

GUMP++ team members responsible for areas such as PC, SCM, metrics, etc. are encouraged to leave detailed notes here to aid others in the future. The file name should indicate the job function (e.g. SCM, etc) and the date (e.g.YYYYMMDD).

2.4.6 TISK Directory

All TISK documents will be maintained in the appropriate TISK directory. These files should be named so that they can be easily identified. It is recommended using the suffix YYYYMMDD for multiple versions of a file (e.g., report19950601, report19950715, etc.) Suggested filenames for common process files are given in Table 3.

The TISK directory will also contain a soft link (created with the Unix "ln -s" command) to each of the DR's for that TISK. For example, if TISK 1 pertained to Deficiency number 3, the TISK directory T001 would contain a file called DR003 which is a simple link to the file DR003 in the DR directory.

Table 3. TISK Directory Naming Conventions

3.0 SCM GROUP RESPONSIBILITIES

3.1 PARTICIPATION IN THE TISK PROCESS

The GUMP++ process defines specific actions that the SCM group performs in certain process cells. Refer to the GENERIC PROCESS ARCHITECTURE document for details.

In general, the SCM group is responsible for knowing at all times which baseline files will be modified by each TISK. SCM participates in the Change Control Board to guarantee that two TISKS will not be scheduled if they need to update the same file. Occasionally minor conflicts may be allowed, for example if two TISK teams need to make changes to different parts of a user manual or header file. In this case the SCM group must make sure the PC and the entire GUMP++ team understand the conflict and must carefully monitor check-out and check-in to merge the changes correctly.

3.2 CHECK-OUT AND CHECK-IN

The Product Baseline files are kept under version control using a Version Control Tool. The Source Code Control System (sccs) is the version control tool currently used and the following descriptions assume its use. However the SCM group may choose to adopt a different tool in the future.

Any GUMP++ team member may obtain a read-only copy of any baseline file using the "sccs get" command. No specific authorization or permission is required.

When a baseline file is to be changed as part of a TISK, a "check-out" is required to lock the file and prevent simultaneous change by another user. Check-out is performed only by the SCM group using the "sccs edit" command. The writeable version is passed to the Software Engineer who will make the changes.

When the changes have been made, the Software Engineer passes the file back to the SCM group for check-in.

Before check-in the SCM group must verify that the file contains the sccs " ID keywords" in some form similar to Figure 1. The SCCS get command expands these keywords to put file name and version information into the file. See the man page for sccs-get for further information. The precise location of the keywords will vary according to the type of file. Normally they are put into a comment near the top of code files, and into some standard location near the top of documentation files.

Figure 1. Recommended Standard SCCS Header

The SCM group then checks in the file using the "sccs delta" command. It is important to include the TISK number (e.g "T009") in the history comments given during check-in so that the files updated by each TISK can be identified.

If a TISK requires adding a new file to the baseline, the SCM group will add it using the "sccs admin" command. Note that special flags must be used when adding a binary file, such as a gif or jpg. See the sccs man pages for more information.

3.3 FILE STATUS REPORTING

Every week the SCM group will check the status of all baseline files (using the "sccs check" command) noting which TISK is responsible for each file being edited. A simple status report is presented at the class meeting.

3.4 PREPARING A NEW RELEASE

The SCM group, in conjunction with any assigned Software Engineers, is responsible for preparing each new release (a.k.a. "distribution") of each software product. The release process varies from product to product but may be quite complex, since many files may need to be extracted from the Version Control Tool, edited to contain the correct version information, compiled several times to produce different product versions, and moved to the distribution web site. The files how_to_notes/SCMSpecificsRecon3_xxxx describe the process for preparing a release of Recon3. These instructions should be verified to be sure they are up to date.

APPENDIX A

EXAMPLE DIRECTORY STRUCTURE

Top Level Directory:

     /usr/cs/CEN6015FWB/recon/

Directory Structure - April/2000

     /usr/cs/CEN6015FWB/recon/
     /usr/cs/CEN6015FWB/recon/DR
     /usr/cs/CEN6015FWB/recon/IVV
     /usr/cs/CEN6015FWB/recon/IVV/T009
     /usr/cs/CEN6015FWB/recon/IVV/T009/dos
     /usr/cs/CEN6015FWB/recon/IVV/T009/unix
     ...
     /usr/cs/CEN6015FWB/recon/IVV/T051M
     /usr/cs/CEN6015FWB/recon/IVV/gui_rts
     /usr/cs/CEN6015FWB/recon/IVV/r3_rts
     ...
     /usr/cs/CEN6015FWB/recon/IVV/rts
     /usr/cs/CEN6015FWB/recon/SCM
     /usr/cs/CEN6015FWB/recon/SCM/make_distrib
     /usr/cs/CEN6015FWB/recon/SCM/tracking
     /usr/cs/CEN6015FWB/recon/SEPG
     ...
     /usr/cs/CEN6015FWB/recon/SQA
     /usr/cs/CEN6015FWB/recon/demo
     ...
     /usr/cs/CEN6015FWB/recon/distrib
     ...
     /usr/cs/CEN6015FWB/recon/forms
     ...
     /usr/cs/CEN6015FWB/recon/gump
     /usr/cs/CEN6015FWB/recon/gump/SCCS
     ...
     /usr/cs/CEN6015FWB/recon/how_to_notes
     ...
     /usr/cs/CEN6015FWB/recon/metric
     /usr/cs/CEN6015FWB/recon/recon2
     /usr/cs/CEN6015FWB/recon/recon2/SCCS
     ...
     /usr/cs/CEN6015FWB/recon/recon3
     /usr/cs/CEN6015FWB/recon/recon3/SCCS
     ...
     /usr/cs/CEN6015FWB/recon/tisks
     /usr/cs/CEN6015FWB/recon/tisks/T001
     /usr/cs/CEN6015FWB/recon/tisks/T002
     /usr/cs/CEN6015FWB/recon/tisks/T003
     ...
     /usr/cs/CEN6015FWB/recon/tisks/T051M
     /usr/cs/CEN6015FWB/recon/training
     ...

REVISION HISTORY