CVS-CHEAT-SHEET

CVS Cheat Sheet for fptools hackers.
------------------------------------

At Glasgow, we use CVS (Concurrent Version System) to keep track of
our sources for various software projects.  CVS lets several people
work on the same software at the same time, allowing changes to be
checked in incrementally.

The full documentation for CVS is online, in info format (use 'info
cvs' or run emacs and type C-h i).  A good source of tips is the CVS
FAQ, in /local/doc/gnu/CVS.FAQ.  Bradley C. Kuszmaul provides a "to
the point" introduction to CVS at

	http://arch.cs.yale.edu:8080/~bradley/cvs-instructions

This note is supposed to be a set of guidelines for how to use CVS at
Glasgow, and will probably evolve in time.  The main thing to remember
is that most mistakes can be undone, but if there's anything you're
not sure about feel free to bug the local CVS meister (namely Me
<simonm@dcs.gla.ac.uk>).

The following guidelines should mean we don't step on each other's
toes too much.  Ok, here's what you do:

* (only if using CVS remotely, i.e. not at Glasgow):

  To use remote CVS, you need to supply me with a username and
  encrypted password.  Once you've done that and the account has been
  set up, you need to do:

     cvs -d <username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot login

  CVS will ask for a password.  You only need to enter the password once, 
  it will be recorded in .cvspass in your home directory.

     setenv CVSROOT :pserver:<username>@solander.dcs.gla.ac.uk:/local/fp/src/cvsroot

  The CVSROOT environment variable will be recorded in the checked-out
  tree, so you don't need to set this every time either.  Ignore the
  instructions for setting CVSROOT below.

* (ok, everybody now...) Firstly, identify which areas of the source
  tree you'll be working on.  The directory structure looks like this:

	fptools/ghc		GHC
	fptools/hslibs		Haskell Libraries
	fptools/happy		Happy
	fptools/haggis		Haggis
	fptools/green-card	Green Card
	fptools/nofib		Nofib test suite
	fptools/common-rts	GHC/Hugs combined run-time system

  For each directory, there's a mailing list: fp-cvs-ghc,
  fp-cvs-hslibs etc.  Everyone on the mailing list is sent a message
  automatically by CVS whenever someone checks in a change, this helps
  to keep track of what's going on when several people are working on
  related stuff.  Ask the CVS meister to put you on the relevant
  mailing lists.

* Create a .cvsrc file.  Mine looks like this:

	checkout -P
	release -d
	update -P
	diff -c

  It just gives default flags for some of the CVS commands.  For instance,
  the -P flag to 'checkout' says prune empty directories, which is
  normally what you want.

* Check out your sources.  The Approved Way (at least by me) to do
  this is as follows:

	$ CVSROOT=/local/fp/src/cvsroot
	$ export CVSROOT

	or, if you're using csh or tcsh:
		$ setenv CVSROOT=/local/fp/src/cvsroot

	$ cvs checkout fpconfig

  At this point you have a new directory called 'fptools' which contains
  the basic stuff for the fptools suite - including the configuration
  files and literate programming tools.

	$ mv fptools <directory>

  You can call the fptools directory whatever you like, CVS won't mind.

	$ cd <directory>
	$ cvs checkout ghc hslibs happy

  The second command here checks out the relevant modules you want to
  work on.  For a GHC build, for instance, you need at least ghc and
  hslibs.

* Build the software, if necessary.  Unless you're just working on
  documentation, you'll probably want to build the software in order
  to test any changes you make.  For GHC, instructions can be found
  in the GHC installation guide, online in info format.

* Make changes.  Preferably small ones first.

* Test them.  You can see exactly what changes you've made by using
  the 'cvs diff' command.  For example,

	$ cvs diff

  lists all the changes (using the 'diff' command) in and below the
  current directory.  In emacs, C-c C-v C-= runs 'cvs diff' on the current
  buffer and shows you the results.

* Before checking in a change, you need to update your source tree:

	$ cd fptools
	$ cvs update

  This pulls in any changes that other people have made, and merges them 
  with yours.  If there are any conflicts, CVS will tell you, and you'll 
  have to resolve them before you can check your changes in.  The 
  documentation describes what to do in the event of a conflict.

  It's not always necessary to do a full cvs update before checking in
  a change, since CVS will always tell you if you try to check in a file
  that someone else has changed.  However, you should still update
  at regular intervals to avoid making changes that don't work in
  conjuction with changes that someone else made.  Keeping an eye on
  what goes by on the mailing list can help here.

* When you're happy that your change isn't going to break anything,
  check it in.  For a one-file change:

	$ cvs commit <filename>

  CVS will then pop up an editor for you to enter a "commit message",
  this is just a short description of what your change does, and will
  be kept in the history of the file.  

  If you're using emacs, simply load up the file into a buffer and type
  C-x C-q, and emacs will prompt for a commit message and then check in
  the file for you.

  For a multiple-file change, things are a bit trickier.  There are 
  several ways to do this, but this is the way I find easiest.  
  First type the commit message into a temporary file.  Then either

	$ cvs commit -F <commit-message> <file_1> .... <file_n>

  or, if nothing else has changed in this part of the source tree,

	$ cvs commit -F <commit-message> <directory>

  where <directory> is a common parent directory for all your changes, 
  and <commit-message> is the name of the file containing the commit
  message.

  Shortly afterwards, you'll get some mail from the relevant mailing
  list saying which files changed, and giving the commit message.  
  For a multiple-file change, you should still get only *one* message.

* As a general rule: commit changes in small units, preferably
  addressing one issue or implementing a single feature.  Provide a 
  descriptive log message so that the repository records exactly which 
  changes were required to implement a given feature/fix a bug.  I've 
  found this *very* useful in the past for finding out when a particular
  bug was introduced: you can just wind back the CVS tree until
  the bug disappears.

* Keep the sources at least *buildable* at any given time.  No
  doubt bugs will creep in, but it's quite easy to ensure that any
  change made at least leaves the tree in a buildable state.  We do
  nightly builds of GHC to keep an eye on what things work/don't work
  each day and how we're doing in relation to previous verions.  This
  idea is truely wrecked if the compiler won't build in the first place!

Ok, that'll do for now.

Simon Marlow <simonm@dcs.gla.ac.uk>