SC2012BootcampPlan » History » Version 25

Chris Cannam, 2012-04-24 04:06 PM

1 1 Chris Cannam
h1. Plan for Software Carpentry 2012 Boot Camp on Version Control
2 1 Chris Cannam
3 2 Chris Cannam
h3. Purpose
4 1 Chris Cannam
5 2 Chris Cannam
To explain version control to researchers who have never used it before, or who want to understand it better.
6 2 Chris Cannam
7 2 Chris Cannam
h3. Context
8 2 Chris Cannam
9 2 Chris Cannam
Two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.
10 2 Chris Cannam
11 2 Chris Cannam
h2. Outline
12 3 Chris Cannam
13 3 Chris Cannam
The basic plan is:
14 6 Chris Cannam
15 3 Chris Cannam
 # presentation introduction to version control in general (using either whiteboard drawings or a PowerPoint presentation)
16 3 Chris Cannam
 # long worked example in which basic topics of version control are worked through using EasyMercurial and then some more advanced topics are returned to using the command-line tool
17 3 Chris Cannam
 # closing remarks talking about other tools, other topics of interest etc
18 3 Chris Cannam
19 15 Chris Cannam
h2. Contents
20 15 Chris Cannam
21 15 Chris Cannam
Detailed contents:
22 3 Chris Cannam
23 7 Chris Cannam
 * A presentation introduction to the concept of version control.
24 7 Chris Cannam
 ** What is it for and why is it useful?
25 7 Chris Cannam
 ** What can go wrong without it?
26 7 Chris Cannam
 ** How does a version control system work?
27 7 Chris Cannam
 ** *History* + *Collaboration*
28 3 Chris Cannam
 * Check that participants have EasyMercurial installed and working
29 8 Chris Cannam
 * *Worked example, part 1: Working by myself*
30 5 Chris Cannam
 ** *Topics:* Initialising a repository, committing files, reading history, looking at diffs, reverting unwanted changes, going back in time to look at old versions
31 3 Chris Cannam
 ** We will be working on a recipe for fish stew for a future recipe book
32 3 Chris Cannam
 ** Make a new directory, create a text file @fishstew.txt@ in it, start adding an ingredients list, save
33 4 Chris Cannam
 ** Run up EasyMercurial, "Open" that directory, see @fishstew.txt@ in untracked file list, explain this
34 1 Chris Cannam
 ** Add file, commit, supply a message, note that we now have some history
35 17 Chris Cannam
 ** Make a change, note that files are marked as modified, note possible presence of backup file (ending ~ or .bak) from editor -- _we'll come back to that in a moment_
36 13 Chris Cannam
 ** A changeset records the state of all files, not just one file: add another file, @omelette.txt@ and add that
37 8 Chris Cannam
 ** Commit change, review history, look at the diff
38 1 Chris Cannam
 ** _Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff etc_
39 10 Chris Cannam
 ** Go back to that backup file in My Work, add it to ignored list, commit
40 13 Chris Cannam
 ** The history is not just for information: we can go back to the previous version by updating to it...
41 12 Chris Cannam
 ** ... and then a normal update gets us back to the latest version again
42 11 Chris Cannam
 ** Now, let's say this is the version we send off to our agent to see whether (s)he can sell it to a publisher. (Or whatever we do these days.) Tag it as v0.1 -- _digression about sensible tag names on whiteboard?_
43 12 Chris Cannam
 ** Make and commit another change, just to make the history more interesting
44 11 Chris Cannam
 ** What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
45 16 Chris Cannam
 ** ... but we are still in big trouble if our computer fails. Thus:
46 16 Chris Cannam
 * *Worked example, part 2: Working by myself "with backups"*
47 16 Chris Cannam
 ** *Topics:* Clone, push and pull, using an online repo
48 18 Chris Cannam
 ** Register an account on Bitbucket and create a new private repository
49 18 Chris Cannam
 ** Look up its URL
50 18 Chris Cannam
 ** In EasyMercurial, hit the Push button, enter URL, push to remote repo, check that the history is present and correct on the site
51 20 Chris Cannam
 ** Make another change locally, commit, push, and check the history on site again
52 1 Chris Cannam
 ** Exit EasyMercurial. Delete the local repository / working copy folder completely!
53 20 Chris Cannam
 ** Start EasyMercurial again, see that _(sniff)_ the working copy is lost. Clone it again from Bitbucket and note that the history is all there
54 23 Chris Cannam
 * *Worked example, part 3: Introducing other developers*
55 22 Chris Cannam
 ** *Topics:* Conflicts, merges
56 21 Chris Cannam
 ** Pair up and, in each pair, decide whose Bitbucket repo you will be working on and whose we'll just leave for now. (We should pair the "instructor" with someone as well)
57 21 Chris Cannam
 ** The second person in the pair should then clone the repository from Bitbucket
58 24 Chris Cannam
 ** Both people can then make some edits: they should edit the same file
59 24 Chris Cannam
 ** The _second_ user should push their changes to the remote repo first
60 24 Chris Cannam
 ** The _first_ user then tries to push. They should get the "Push failed... The local repository may have been changed" message
61 25 Chris Cannam
 ** Then the first user pulls instead: history graph now shows two heads