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