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