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
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.)
20 * Basic shell concepts and skills (`ls`, `cd`, `mkdir`, editing
22 * Basic shell scripting (for the discussion of provenance).
27 * Make sure the network is working *before* starting this lesson.
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.
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
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
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
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.