version-control/instructor.md

   1 Version control is the most important practical skill we introduce.
   2 as the last paragraph of the introduction above says, the workflow
   3 matters more than the ins and outs of any particular tool.  By the end
   4 of 90 minutes, the instructor should be able to get learners to chant,
   5 "Update, edit, merge, commit," in unison, and have them understand
   6 what those terms mean and why that's a good way to structure their
   7 working day.
   8
   9 Provided there aren't network problems, this entire lesson can be
  10 covered in 90 minutes.  The example at the end showing how to use
  11 Subversion keywords to track provenance is the "ah ha!" moment for
  12 many learners.  If time is short, skip the material on recovering old
  13 versions of files in order to get to this section instead.  (The fact
  14 that provenance is harder in Git, both mechanically and conceptually,
  15 is one reason to keep teaching Subversion.)
  16
  17 Prerequisites
  18 -------------
  19
  20 * Basic shell concepts and skills (`ls`, `cd`, `mkdir`, editing
  21   files).
  22 * Basic shell scripting (for the discussion of provenance).
  23
  24 Teaching notes
  25 --------------
  26
  27 * Make sure the network is working *before* starting this lesson.
  28
  29 * Give learners a ten-minute overview of what version control does for
  30   them before diving into the watch-and-do practicals.  Most of them
  31   will have tried to co-author papers by emailing files back and
  32   forth, or will have biked into the office only to realize that the
  33   USB key with last night's work is still on the kitchen table.
  34   Instructors can also make jokes about directories with names like
  35   "final version", "final version revised", "final version with
  36   reviewer three's corrections", "really final version", and, "come on
  37   this really has to be the last version" to motivate version control
  38   as a better way to collaborate and as a better way to back work up.
  39
  40 * Version control is typically taught after the shell, so collect
  41   learners' names during that session and create a repository for them
  42   to share with their names as both their IDs and their passwords.
  43   The easiest way to create the repository is to use a server managed
  44   by an ISP such as Dreamhost, or on SourceForge, Google Code, or some
  45   other "forge" site, all of which provide web interfaces for
  46   repository creation and management.  If your learners are advanced
  47   enough to be using SSH, you can instead create it on any server they
  48   can access, and connect with the `svn+ssh` protocol instead of
  49   HTTPS.
  50
  51 * Be very clear what files learners are to edit and what user IDs they
  52   are to use when giving instructions.  It is common for them to edit
  53   the instructor's biography, or to use the instructor's user ID and
  54   password when committing.  Be equally clear *when* they are to edit
  55   things: it's also common for someone to edit the file the instructor
  56   is editing and commit changes while the instructor is explaining
  57   what's going on, so that a conflict occurs when the instructor comes
  58   to commit the file.
  59
  60 * Learners could do most exercises with repositories on their own
  61   machines, but it's hard for them to see how version control helps
  62   collaboration unless they're sharing a repository with other
  63   learners.  In particular, showing learners who changed what using
  64   `svn blame` is only compelling if a file has been edited by at least
  65   two people.
  66
  67 * If some learners are using Windows, there will inevitably be issues
  68   merging files with different line endings.  `svn diff -x -w` is
  69   supposed to suppress differences in whitespace, but we have found
  70   that it doesn't always work as advertised.