[Axiom-developer] CVS tutorial for Developers

[root]

Bill,

CVS is painful to figure out which is one reason why I haven't been
using it. However, I've taken the plunge. Here's the whole of what
I've learned:

I maintain a directory where I work (call this WORK)
  /home/axiomgnu/new
and a directory for CVS (call this GOLD)
  /axiom

When I want to export a set of changes I do the following steps:

0) MAKE SURE THE ~/.ssh/config FILE IS CORRECT:

    (you should only need to do this once. 
     you need to change the User= field)

Host *.gnu.org
  Protocol=1
  Compression=yes
  CompressionLevel=3
  User=axiom
  StrictHostKeyChecking=no
  PreferredAuthentications=publickey,password
  NumberOfPasswordPrompts=2


1) MAKE SURE THE SHELL VARIABLES ARE OK: 

    (normally set in .bashrc)

export CVS_RSH=ssh
export CVSROOT=:pserver:address@hidden:/cvsroot/axiom
                        ^^^^^
                        change this to your id

2) MAKE SURE YOU'RE LOGGED IN:

    (i keep a session open all the time but it doesn't seem to care
     if you login again. i'm not sure what login does, actually)

cvs login

3) IF YOU WANT A FRESH COPY FOR THE FIRST TIME OR AT ANY TIME:

   (you only need to do this the first time but you can erase
    your whole axiom subtree and refresh it again doing this.
 
    note that i work as root so i can update /.  Most rational
    people are smarter than me and work as a regular user so
    you have to change the instructions for cd. But you knew that)

cd /
cvs co axiom


4) MAKE SURE THAT GOLD, MY LOCAL CVS COPY, IS UP TO DATE:

    (i maintain an exact copy of the CVS repository and only make
     changes to it when i want to export the changes. that way i
     won't export my working tree by accident. my working tree is
     normally badly broken.

     The update command makes sure that you have all of the changes
     other people might have made and checked in. you have to merge
     your changes carefully so you don't step on other people's work.
     So be sure to run update BEFORE you copy files to GOLD)     

cd /axiom
cvs update

5) COPY THE CHANGED FILES FROM THE WORK TREE TO THE GOLD TREE:

    (This is an example for updating the *.daase files.
     You basically are changing your GOLD tree to reflect the
     way you want CVS to look once you check in all of the files.
     Since you want to check in your new daase files this will do it)

cp /home/axiomgnu/new/src/share/algebra/*.daase /axiom/src/share/algebra

6) IF A FILE IS NEW (e.g. src/interp/foo.lisp.pamphlet) THEN:

    (If you create a file you need to "put it under CVS control"
     CVS only cares about files you explicitly add or delete.
     If you make a new file and copy it to GOLD you need to do this.

     Don't do the "cvs add" in your WORK directory. The cvs add
     command updates the files in the CVS directory and you won't
     have them in your WORK directory. 

     Notice that you do the "cvs add" in the directory where the
     file was added (hence, the cd commands).

cd /axiom/src/interp
cvs add -m"some pithy comment" foo.lisp.pamphlet
cd /axiom

7) IF A FILE IS DELETED (e.g. src/interp/foo.lisp.pamphlet) THEN:

   (you have to delete the file from the GOLD directory BEFORE you
    do a "cvs remove". The "cvs remove" will update the files in
    the CVS directory

     Notice that you do the "cvs remove" in the directory where the
     file was deleted (hence, the cd commands).

cd /axiom/src/interp
rm foo.lisp.pamphlet
cvs remove foo.lisp.pamphlet
cd /axiom

8) IF A DIRECTORY IS NEW (e.g. foodir) THEN:

    (this will put "foodir" under CVS control. It will also create
     foodir/CVS as a directory with a bunch of control files in the
     foodir/CVS directory. Don't mess with the control files.

    (there are a bunch of special rules about directories.
     empty directories are not downloaded by update.)

    (NOTE: THERE IS NO WAY TO DELETE A DIRECTORY)

cd /axiom/src
mkdir foodir
cvs add -m "pithy comment" foodir
cd /axiom

9) edit CHANGELOG:

   (The CHANGELOG is there so we have some clue what changed.
    CVS also keeps track of this but I haven't figured out the
    details yet so the CHANGELOG is a manual file for the moment

    CHANGELOG is already under CVS control so it will get uploaded
    when you do the checkin.)

cd /axiom
emacs -nw CHANGELOG
 (add a date, initials, and pithy comment, save it, and exit)

9) CHECK IN THE CHANGES

   (This will actually change the savannah CVS repository.

    The "cvs ci" command will recurse thru all of the lower
    subdirectories and look for changed files. It will change
    the host versions of those files to agree with your copy.
    If somebody else has changed a file while you were busy
    screwing around then the checkin MAY complain (if it can't
    merge the changes)

cd /axiom
cvs ci -m"pithy comment"

Congrats. You've now done your first real damage to the production
image. Please be very careful as this is a world-readable copy and
we don't want to ship nonsense. Test EVERYTHING, no matter how trivial
the change, BEFORE you upload. But I didn't need to tell you that :-)

Tim
address@hidden
address@hidden