9 Team Development

 
  <--Last Chapter Table of Contents Next Chapter-->  
 

9.1 Change Logs

The Change Log

Creating a change log is the easiest method to document changes you've made in a project. A change log is a text file (usually called "CHANGES") containing an explaination of all recent changes in a project. For example, if you are working on an open source project and you add support for encrypted passwords, you might document this by writing

  Nov 1 - added password support to file passwords.adb
 

If anyone was going to add password support to your project, they can quickly see that you've already done it. Or if somebody was adding additional features to the passwords.c file, they will know that they may have to change their work since you've already changed the same file.

The change log is popular on open source projects involving few programmers because there's little chance of two programmers modifying the same source file simultaneously.

The Formal Change Log
 
Most businesses or professional institutions have a much more formal structure for their change logs. In an environment involving important data, a program problem means someone else will have to retrace your activities in order to find and correct a problem.

Formal logs are kept in a binder since there's always the possibility that a major failure will make it impossible to sign onto the computer. Each change is documented with

Some companies have internal audits done to ensure that changes were properly made. The auditors will pick random pages from the change log and ask the programmer to verify the changes. In these cases, a formal change log may also include information such as the size, ownership and permissions of files affected. This serves both to quickly check a file as well as to force a programmer to verify the security of the files he or she installs. The most common security loopholes in UNIX are caused by people not checking the ownership and permissions of installed files.

9.2 RCS: Revision Control System

RCS (Revision Control System) is a tool that shares a document or program source code between multiple people. It also automatically numbers the file with a version number (eg. 1.1, 1.2) with each revision, and maintains a change log. CVS, an extension to RCS, is described below.Once you initialize RCS for a project, people in your project "check out" (with the co command) a copy of a file, and when they're done making changes they "check in" the file (with the ci command).

RCS is also a good tool for maintaining documentation.

Read the rcsintro man page for more information on getting started.

The following is a transcript of a session using RCS. Assume that you have a source file called "f.c". To add the source file to RCS, you'd use ci. You are prompted for a general description of the file and RCS assigns version number 1.1 to the file. The file is deleted from your directory and moved into RCS's care.

armitage:/home/ken/ada/rcs# ci f.c
RCS/f.c,v <--f.c
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>>
Curreny Definitions
>> .
initial revision: 1.1
done
armitage:/home/ken/ada/rcs# ls
RCS

To check out the file, read-only, use co. The file reappears.

armitage:/home/ken/ada/rcs# co f.c
RCS/f.c,v -->f.c
revision 1.1
done
armitage:/home/ken/ada/rcs# ls
RCS f.c

To check out a file to change it, use co -l (lock out others):

armitage:/home/ken/ada/rcs# co -l f.c
RCS/f.c,v --> f.c
revision 1.1 (locked)
done

Suppose you add the line "--test line" to the file. Rcsdiff will report any changes you've made to the file since checking it out:

armitage:/home/ken/ada/rcs# rcsdiff f.c
===================================================================
RCS file: RCS/f.c,v
retrieving revision 1.1
diff -r1.1 f.c
0a1
> --test line

Finally, you can check the file back in. RCS increments the version number and prompts you for a message for the change log.

armitage:/home/ken/ada/rcs# ci f.c
RCS/f.c,v <-- f.c
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> Added comments
>> .
done

9.3 CVS: Concurrent Versions System

CVS (Concurrent Versions System ) is a front end to RCS designed to work with groups of files in multiple directories. CVS can work with individual files, whole directories or you can organize large projects into groups of files (called a modules) that you want to work with.  Like RCS, it timestamps files, maintains version numbers, and identifies possible problems when two programmers update the same section of a program simultaneously.

CVS is very popular for open source development. CVS can be configured to allow programmers all over the world to work on your project without having to be logged into your computer.

In order to use CVS, the project leader needs to create a directory for CVS to work in (called the repository) and a subdirectory called CVSROOT. Then you define an environment variable called CVSROOT so CVS knows where to find the CVS directory.  For example, to make "/home/our-project-cvs" the repository for your team, set up the CVSROOT under bash as

export CVSROOT=/home/our-project-cvs

The repository holds  copies of all the files, change logs, and other shared resources for your project.

To add a new project to the CVS repository, use the import command. Import will take the files in the current directory and put them in the repository under the name you specify. Import also requires a short string to identify who is adding the project, and a string to describe the state of the project. This strings are comments and can be anything: your login and "init-rel" for initial release may be good choices.

By convention, CVS begins numbering your project with "1.1"

[root@redbase cvs]# cvs import project kburtch init-rel
(CVS starts your default editor, typically vi)
CVS: ----------------------------------------------------------------------
CVS: Enter Log. Lines beginning with `CVS: ' are removed automatically
CVS:
CVS: ----------------------------------------------------------------------
(make notes and exit vi)
N project/currency.adb
No conflicts created by this import

The "N project/currency.adb" line indicates that CVS created a new project called "project" and added the Ada file currency.adb to it. currency.adb is now stored in the CVS repository, ready to be shared amongst the team members.

To work with a project, you use co (or checkout). This CVS command will save a copy of the project in your directory. It will also create a CVS directory to save private data files used by CVS. To use co, move to your home directory and type:

[root@redbase cvs]# cvs checkout currency.adb
cvs checkout: Updating .
U project/currency.adb

The subdirectory project will contain your own, personal copies of project files to work on. CVS maintains the original copy of currency.adb. Another programmer can also checkout currency.adb while you are working on your copy.

If you do a checkout right after an import, you may have to remove the original files: CVS will not overwrite any existing files.

To add a file to CVS, use the add command.  To add a file called currency.adb, use

[root@redbase cvs]# cvs add currency.adb
 
 

NoteSingle files, directories or even CVS modules can also be added to your project using "add".

As you work on your source code, you can check your work against the project using the update command.

[root@redbase cvs]# cvs update
cvs update: Updating .

When updating, CVS checks the files in your copy of the project against its copies. If another team member made changes to one of the project Ada files, CVS will copy the new file to your directory.

If another team member made changes to one of the Ada files you've been working on, CVS will attempt to update your copy without destroying your work.

Sometimes the changes involve the same part of the Ada file and CVS won't be able to combine the changes automatically. CVS calls this a conflict. For example, suppose your Ada file contained a function 

function ConvertCurrency( amount : integer ) return float;

If you changed this function to use a float amount, and another team member has changed amount to a string, CVS will report a conflict. You will have to talk to the team member who made the change and make an agreement what amount should be.

If there are no other problems after an update, you can continue working on your source code.

To delete a file, remove it using "rm" and then "update".  CVS will see your file is no longer in the project.
 
 

NoteThe CVS command release will permanently remove a file from a project (including the copy in CVSROOT), but it also prevents you from recovering the file from the CVSROOT directory in an emergency.  Unless storage space is limited, consider using the rm/update method of removing files.

While working on your source code, your changes are not distributed to the rest of your team until you are ready.  When your source code is tested and ready to be made available, use ci (or commit). Before commiting your changes, delete non-essential files (such as .ali, .o or executable files) to save space in the repository.

The log command gives information about a group of files:

[root@redbase cvs]# cvs log -l project
cvs log: Logging project
RCS file: /usr/cvs/project/currency.adb,v
Working file: project/currency.adb
head: 1.1
branch: 1.1.1
locks: strict
access list:
symbolic names:
p1: 1.1.1.1
keyword substitution: kv
total revisions: 2; selected revisions: 2
description:
----------------------------
revision 1.1
date: 1999/01/13 17:27:33; author: kburtch; state: Exp;
branches: 1.1.1;
Initial revision
----------------------------
revision 1.1.1.1
date: 1999/01/13 17:27:33; author: kburtch; state: Exp; lines: +0 -0
Project started
=============================================================================

Status gives you an overview of a group of files:

[root@redbase cvs]# cvs status project
cvs status: Examining project
===================================================================
File: currency.adb Status: Up-to-date
Working revision: 1.1.1.1 Wed Jan 13 17:27:33 1999
Repository revision: 1.1.1.1 /usr/cvs/project/currency.adb,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)

9.4 Creating Transcripts with Script

So you did something wrong. How to you show what you did to your fellow programmers? The script command creates a file called "typescript" in the current directory. The typescript file is a text file that records a list of everything that appears on the screen. You can stop the recording process with the exit command.
 

9.5 Timing Execution with Time

The shell command time will tell you how long a program took to run, and reports general statistics such as how many page faults occurred. 
armitage:/home/ken/ada/sm# time myprog
3.09user 0.95system 0:05.84elapsed 69%CPU(0avgtext+0avgdata 0maxresident)k
0inputs+0outputs(4786major+4235minor)pagefaults 0swaps
 
  <--Last Chapter Table of Contents Next Chapter-->