Some tips on how to manage your project code

Your projects are done in groups of 2. Both of you will be creating, deleting, modifying different parts of the project code as the semester goes. The question is, what is the best way to manage your code base? Here are some of the things you may want to consider:

separable working code: each of you should have a separate "working" directories. So when you are editing a file, you don't want your partner to use that file until it is ready.
consistent: once the code is ready, you want to make your code visible to your partner.
reversible: you can return to yesterday's code when needed.
collision-free: both of you don't modify the same file at the same time.

The first thing you should do is to divide up the files such that each file is assigned an owner. For example, if one person is doing the firewalling, he would own firewall.c, and if the other person is doing the IP layer, she would own ip_io.c. If you find that both of you need to modify the same file frequently, it may be a sign that you should break up that file into two pieces.

After you break down the files, you should think about how to manage the files so that they can be separable, consistent, reversible, and collision-free. We list three approaches below, with varying degree of complexity. You should discuss with your partner how you will manage the code. Our recommendation is that you use RCS.

"4 Directories" Approach

Under your shared <project> directory, there are four directories:

common: files that are considered "stable"
user1: user 1's working directory
user2: user 2's working directory
backup: backup of files

The idea here is that common directory contains a version of the source code that is "stable". user1 and user2 are your individual working directory, where you can develop, compile, and test your code. Most of the source files in user1 or user2 are soft links (symbolic links) to files in common directory; this implies that when files in common are updated, the corresponding files in your working directory are automatically updated. When you want to modify a file, you will first make a copy of the file from common dir to your working dir. When you are ready to make that updated file visible to your partner, you put it back to common dir. Simple.

To setup your working directory, first put all of your files in common dir, and then

    cd user1              # cd to your working dir
    ln -s ../common/* .   # soft (symbolic) link all the files in common dir to your dir

To modify a file, make a copy of the file from common dir to your working dir:

    cd user1
    cp ../common/<file> ./

When you are ready to make your file visible, copy that file from your working dir to common

    cd user1
    cp <file> ../common/

If you want to give up the ownership of <file>, remove <file> from your working dir, and make it a soft link. Thus, if your partner later puts update of <file> in common dir, you will automatically see the change.

   cd user1
   rm <file>                      # remove your
   ln -s ../common/<file> <file>  # make this file in your working dir a soft link

Now if you want to make backup, just make a copy of common (and possibly your working directories) to backup dir, such as

   cd <project dir>
   cp -r common backup/common.0305   # common dir backup on March 5

RCS

RCS (Revision Control System) is a piece of software that facilitate a group of people to develop code together. It allows you to lock a file (so that no one else can modify it) and track file revisions (so that you can get back to previous versions). Here is one way to setup and use RCS:

1. Create your RCS directory and two working directories. You can choose the names of <user1> and <user2>.

    cd <project dir>
    mkdir RCS <user1> <user2>
    cd <user1>
    ln -s ../RCS .
    cd ../<user2>
    ln -s ../RCS .

Now each of you has a working directory.

2. Prepare your files: copy all of the source code you have into <project dir>/<user1>, which contains Makefile, some .c and .h files. First, you should add the following headers to the beginning of your source files:

For each source file (.h and .c files), add the following header

       /*  $Id$
        *  $Log$
        */

For Makefile, add the following header

       # $Id$
       # $Log$

These header fields will be automatically filled in every time you "check-in" your code to RCS. It will show who and when the modification occurred for the files.

3. Insert files to the RCS repository:

     cd <user1>
     ci -u -m"<log message>" *.c *.h Makefile

Follow the direction and enter the description of each file. When you are done, the RCS repository has the initial version of the files, and user1 dir has a read-only version of the source code.

4. Set up your partner's directory (user2)

     cd <user2>
     cp ../user1/*.c ../user1/*.h ../user1/Makefile .
     co -r *.c *.h Makefile

Now your partner (user2) also has a read-only version of the source code.

5. When you (user1) want to edit <file>, you need to first check out <file> by doing

     cd <user1>
     co -l <file>

"-l" option locks <file> in RCS (so that your partner cannot edit it), and it sets the permission of <file> in your local directory read/write, so you can edit it.

6. When you are done, check in <file> by doing

     ci -u -m"<log message>" <file>

"-u" returns the lock back to RCS (so that your partner can later acquire the lock if needed). It sets the permission of <file> in your local directory read-only.

7. Important: when your partner makes a file update to RCS, you don't get that update automatically, unless you explicitly "check out" that file. So every once in a while, you should do

      co -r <file>   # if you know exactly which file you want to update
   or 
      co -r *        # if you want to update all files

If you are currently modifying a file, "co -r" will not automatically replace that file. It would prompt you whether you want to delete your local copy, and you can just say "no".

8. There are many other useful functionalities in RCS. We encourage you to explore rcsdiff, which allows you to compare different revisions. "co -d<date>" allows you to retrieve a snapshot of code on a selected date. There are also ways to tag a snapshot of code.

It is very important to know that once you check out a file, you hold a lock on the file. Your partner will NOT be able to modify, until you check in the file again. So check out the files only when you need to edit it, and when you are done editing, check it in again.

You should put only the important files under RCS control, such as *.c, *.h, and Makefile. You should not put .o files or temporary test cases under RCS, for example.

For more information about RCS, read the man page (man rcs, man ci, man co). Also I find this RCS tutorial helpful.

CVS

Some people like to use CVS (Concurrent Versions System) instead of RCS. CVS builds on top of RCS and it provides additional functionalities not available in RCS. We provide you with the following references if you are interested:

CVS tutorial slides (Note: this tutorial uses "cvsinit" to create the CVS repository. Use "cvs init" instead.)
CVS manual at cvshome.org

By Yang-hua Chu, yhchu@cs.cmu.edu
CVS links modified by An-Cheng Huang, pach@cs.cmu.edu
RCS link modified by Urs Hengartner, uhengart+@cs.cmu.edu