[project @ 1997-10-24 09:39:36 by simonm]

add CVS guidelines file

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.
+
+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:
+
+* 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>
+