CVS-CHEAT-SHEET

   1 CVS Cheat Sheet for fptools hackers.
   2 ------------------------------------
   3
   4 At Glasgow, we use CVS (Concurrent Version System) to keep track of
   5 our sources for various software projects.  CVS lets several people
   6 work on the same software at the same time, allowing changes to be
   7 checked in incrementally.
   8
   9 The full documentation for CVS is online, in info format (use 'info
  10 cvs' or run emacs and type C-h i).  A good source of tips is the CVS
  11 FAQ, in /local/doc/gnu/CVS.FAQ.  Bradley C. Kuszmaul provides a "to
  12 the point" introduction to CVS at
  13
  14         http://arch.cs.yale.edu:8080/~bradley/cvs-instructions
  15
  16 This note is supposed to be a set of guidelines for how to use CVS at
  17 Glasgow, and will probably evolve in time.  The main thing to remember
  18 is that most mistakes can be undone, but if there's anything you're
  19 not sure about feel free to bug the local CVS meister (namely Me
  20 <simonm@dcs.gla.ac.uk>).
  21
  22 The following guidelines should mean we don't step on each other's
  23 toes too much.  Ok, here's what you do:
  24
  25 * Firstly, identify which areas of the source tree you'll be working
  26   on.  The directory structure looks like this:
  27
  28         fptools/ghc             GHC
  29         fptools/hslibs          Haskell Libraries
  30         fptools/happy           Happy
  31         fptools/haggis          Haggis
  32         fptools/green-card      Green Card
  33         fptools/nofib           Nofib test suite
  34         fptools/common-rts      GHC/Hugs combined run-time system
  35
  36   For each directory, there's a mailing list: fp-cvs-ghc,
  37   fp-cvs-hslibs etc.  Everyone on the mailing list is sent a message
  38   automatically by CVS whenever someone checks in a change, this helps
  39   to keep track of what's going on when several people are working on
  40   related stuff.  Ask the CVS meister to put you on the relevant
  41   mailing lists.
  42
  43 * Create a .cvsrc file.  Mine looks like this:
  44
  45         checkout -P
  46         release -d
  47         update -P
  48         diff -c
  49
  50   It just gives default flags for some of the CVS commands.  For instance,
  51   the -P flag to 'checkout' says prune empty directories, which is
  52   normally what you want.
  53
  54 * Check out your sources.  The Approved Way (at least by me) to do
  55   this is as follows:
  56
  57         $ CVSROOT=/local/fp/src/cvsroot
  58         $ export CVSROOT
  59
  60         or, if you're using csh or tcsh:
  61                 $ setenv CVSROOT=/local/fp/src/cvsroot
  62
  63         $ cvs checkout fpconfig
  64
  65   At this point you have a new directory called 'fptools' which contains
  66   the basic stuff for the fptools suite - including the configuration
  67   files and literate programming tools.
  68
  69         $ mv fptools <directory>
  70
  71   You can call the fptools directory whatever you like, CVS won't mind.
  72
  73         $ cd <directory>
  74         $ cvs checkout ghc hslibs happy
  75
  76   The second command here checks out the relevant modules you want to
  77   work on.  For a GHC build, for instance, you need at least ghc and
  78   hslibs.
  79
  80 * Build the software, if necessary.  Unless you're just working on
  81   documentation, you'll probably want to build the software in order
  82   to test any changes you make.  For GHC, instructions can be found
  83   in the GHC installation guide, online in info format.
  84
  85 * Make changes.  Preferably small ones first.
  86
  87 * Test them.  You can see exactly what changes you've made by using
  88   the 'cvs diff' command.  For example,
  89
  90         $ cvs diff
  91
  92   lists all the changes (using the 'diff' command) in and below the
  93   current directory.  In emacs, C-c C-v C-= runs 'cvs diff' on the current
  94   buffer and shows you the results.
  95
  96 * Before checking in a change, you need to update your source tree:
  97
  98         $ cd fptools
  99         $ cvs update
 100
 101   This pulls in any changes that other people have made, and merges them
 102   with yours.  If there are any conflicts, CVS will tell you, and you'll
 103   have to resolve them before you can check your changes in.  The
 104   documentation describes what to do in the event of a conflict.
 105
 106   It's not always necessary to do a full cvs update before checking in
 107   a change, since CVS will always tell you if you try to check in a file
 108   that someone else has changed.  However, you should still update
 109   at regular intervals to avoid making changes that don't work in
 110   conjuction with changes that someone else made.  Keeping an eye on
 111   what goes by on the mailing list can help here.
 112
 113 * When you're happy that your change isn't going to break anything,
 114   check it in.  For a one-file change:
 115
 116         $ cvs commit <filename>
 117
 118   CVS will then pop up an editor for you to enter a "commit message",
 119   this is just a short description of what your change does, and will
 120   be kept in the history of the file.
 121
 122   If you're using emacs, simply load up the file into a buffer and type
 123   C-x C-q, and emacs will prompt for a commit message and then check in
 124   the file for you.
 125
 126   For a multiple-file change, things are a bit trickier.  There are
 127   several ways to do this, but this is the way I find easiest.
 128   First type the commit message into a temporary file.  Then either
 129
 130         $ cvs commit -F <commit-message> <file_1> .... <file_n>
 131
 132   or, if nothing else has changed in this part of the source tree,
 133
 134         $ cvs commit -F <commit-message> <directory>
 135
 136   where <directory> is a common parent directory for all your changes,
 137   and <commit-message> is the name of the file containing the commit
 138   message.
 139
 140   Shortly afterwards, you'll get some mail from the relevant mailing
 141   list saying which files changed, and giving the commit message.
 142   For a multiple-file change, you should still get only *one* message.
 143
 144 * As a general rule: commit changes in small units, preferably
 145   addressing one issue or implementing a single feature.  Provide a
 146   descriptive log message so that the repository records exactly which
 147   changes were required to implement a given feature/fix a bug.  I've
 148   found this *very* useful in the past for finding out when a particular
 149   bug was introduced: you can just wind back the CVS tree until
 150   the bug disappears.
 151
 152 * Keep the sources at least *buildable* at any given time.  No
 153   doubt bugs will creep in, but it's quite easy to ensure that any
 154   change made at least leaves the tree in a buildable state.  We do
 155   nightly builds of GHC to keep an eye on what things work/don't work
 156   each day and how we're doing in relation to previous verions.  This
 157   idea is truely wrecked if the compiler won't build in the first place!
 158
 159 Ok, that'll do for now.
 160
 161 Simon Marlow <simonm@dcs.gla.ac.uk>
 162