SC2012BootcampPlan » History » Version 83

Chris Cannam, 2013-02-05 05:21 PM

1 78 Chris Cannam
h1. Plan for Software Carpentry 2012 Boot Camps on Version Control
2 1 Chris Cannam
3 43 Chris Cannam
h2. About the session
4 1 Chris Cannam
5 43 Chris Cannam
The session is a two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.
6 2 Chris Cannam
7 77 Chris Cannam
Its goal is to explain version control to researchers who have never used it before, or who want to understand it better.
8 1 Chris Cannam
9 1 Chris Cannam
h2. Outline
10 2 Chris Cannam
11 3 Chris Cannam
The basic plan is:
12 1 Chris Cannam
13 83 Chris Cannam
 # "Presentation introduction":https://code.soundsoftware.ac.uk/attachments/647/VersionControlT.pdf to version control in general
14 43 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
15 43 Chris Cannam
 # Closing remarks talking about other tools, other topics of interest etc
16 3 Chris Cannam
17 43 Chris Cannam
h2. Worked example
18 7 Chris Cannam
19 43 Chris Cannam
Preliminary: Check that participants have EasyMercurial installed and working. All of the following exercises will be using EasyMercurial unless it says otherwise.
20 7 Chris Cannam
21 43 Chris Cannam
h3. Part 1: Working by yourself
22 43 Chris Cannam
23 43 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
24 43 Chris Cannam
25 44 Chris Cannam
We will be working on a recipe for fish stew for a future recipe book.
26 44 Chris Cannam
27 45 Chris Cannam
h4. Adding your first file
28 44 Chris Cannam
29 44 Chris Cannam
 * Make a new directory, create a text file @fishstew.txt@ in it, start adding an ingredients list, save
30 58 Chris Cannam
 * Run up EasyMercurial; enter user name and email address
31 58 Chris Cannam
 * "Open" that directory, see @fishstew.txt@ in untracked file list: that means the version control system is not going to keep track of any changes unless we tell it to
32 44 Chris Cannam
 * Add file: that tells the version control system to keep track of any future changes to it
33 44 Chris Cannam
 * Commit: that sets in stone our having added the file. A commit is a checkpoint
34 44 Chris Cannam
 * Supply a message, note that we now have some history
35 44 Chris Cannam
36 44 Chris Cannam
h4. Changing things
37 1 Chris Cannam
38 44 Chris Cannam
 * Edit the file, change something, save it
39 58 Chris Cannam
 * Note that the file is now marked as modified. (We might also see a backup file ending ~ or .bak from that editor -- ignore it for now, we'll come back to it in a moment)
40 44 Chris Cannam
 * Each revision records the state of all files, not just one file: add another file, @omelette.txt@ and add that
41 44 Chris Cannam
 * Commit change, note that we now have two revisions
42 44 Chris Cannam
 * Review the history and look at the diff
43 44 Chris Cannam
44 44 Chris Cannam
h4. Managing history
45 44 Chris Cannam
46 44 Chris Cannam
 * The history is not just for information: we can go back to the previous version by updating to it...
47 44 Chris Cannam
 * ... and then a normal update gets us back to the latest version again
48 44 Chris Cannam
49 44 Chris Cannam
Let's say this version is the one that we're going to send off to our agent, to see whether they can sell it to a publisher (or whatever we do in these modern times).
50 44 Chris Cannam
51 44 Chris Cannam
 * Tag the current revision as v0.1 -- _digression about sensible tag names on whiteboard?_
52 44 Chris Cannam
 * We can now identify this version easily in the history
53 44 Chris Cannam
 * Make and commit another change, this one involving renaming a file
54 1 Chris Cannam
 * What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
55 1 Chris Cannam
56 80 Chris Cannam
Ignoring something we don't want:
57 1 Chris Cannam
58 1 Chris Cannam
 * Go back to that backup file in My Work, add it to ignored list, commit
59 81 Chris Cannam
60 81 Chris Cannam
_Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff, hg update etc_
61 80 Chris Cannam
62 44 Chris Cannam
Now we have history, but we are still in big trouble if our computer fails. Thus...
63 44 Chris Cannam
64 44 Chris Cannam
h3. Part 2: Working by yourself, but "with backups"
65 44 Chris Cannam
66 48 Chris Cannam
*Topics:* Push, clone, using an online repo hosting service
67 44 Chris Cannam
68 47 Chris Cannam
h4. Pushing local repository to a remote one
69 46 Chris Cannam
70 46 Chris Cannam
 * Register an account on Bitbucket and create a new private repository
71 46 Chris Cannam
 * Look up its URL
72 46 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
73 46 Chris Cannam
74 47 Chris Cannam
h4. Synchronising new changes
75 46 Chris Cannam
76 46 Chris Cannam
 * Make another change locally, commit (perhaps do this more than once before pushing)
77 46 Chris Cannam
 * Push the change(s), and check the history on site again
78 46 Chris Cannam
79 47 Chris Cannam
h4. Recovering from a disaster
80 46 Chris Cannam
81 46 Chris Cannam
 * Exit EasyMercurial. Delete the local repository / working copy folder completely!
82 46 Chris Cannam
 * Start EasyMercurial again, see that _(sniff)_ the working copy is lost
83 46 Chris Cannam
 * Clone it again from Bitbucket and note that the history is all there
84 46 Chris Cannam
85 46 Chris Cannam
_Digression: Note command-line usage again, hg push, hg pull, hg clone: show a sequence of clones, modifying the last one and pushing back along the chain?_
86 1 Chris Cannam
87 48 Chris Cannam
h3. Part 3: Introducing other developers
88 48 Chris Cannam
89 48 Chris Cannam
*Topics:* Conflicts, merges, pull, annotate
90 48 Chris Cannam
91 48 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).
92 1 Chris Cannam
93 48 Chris Cannam
_Remark: in real-world use, this could very well be the same person just using two different computers_
94 1 Chris Cannam
95 58 Chris Cannam
h4. Getting someone else's changes
96 1 Chris Cannam
97 1 Chris Cannam
 * The second person in the pair should then clone the repository from Bitbucket
98 58 Chris Cannam
 * They should then change something and commit it
99 58 Chris Cannam
 * First person pulls -- notes that there are no changes there (merely committing it doesn't put it on the server)
100 58 Chris Cannam
 * Second person pushes
101 58 Chris Cannam
 * First person pulls again -- the change is now in the history but not in the working copy
102 58 Chris Cannam
 * First person updates -- the change is now in the working copy!
103 58 Chris Cannam
104 58 Chris Cannam
h4. Making alternative versions
105 58 Chris Cannam
106 58 Chris Cannam
 * Both people now make some edits: they should edit _two different_ files and commit them
107 48 Chris Cannam
 * The _second_ user should push their changes to the remote repo first
108 48 Chris Cannam
 * The _first_ user then tries to push. They should get the "Push failed... The local repository may have been changed" message
109 48 Chris Cannam
 * Then the first user pulls instead. (Perhaps checks the Incoming list first?)
110 48 Chris Cannam
 * See that the history graph now shows two heads
111 48 Chris Cannam
112 48 Chris Cannam
_Digression on sociological nature of conflict_ a la Greg if feeling expansive
113 48 Chris Cannam
114 48 Chris Cannam
h4. Merging non-conflicting changes
115 48 Chris Cannam
116 48 Chris Cannam
 * Hit Merge, see that the merge happens straight away
117 48 Chris Cannam
 * Remark that this is the point at which you would now test the merged version
118 48 Chris Cannam
 * Commit, push, get collaborator to pull
119 48 Chris Cannam
120 48 Chris Cannam
h4. Resolving conflicts
121 48 Chris Cannam
122 48 Chris Cannam
 * Get each person to edit the same file, in conflicting ways
123 48 Chris Cannam
 * Again, both users should try to push and the push should fail for the later one
124 48 Chris Cannam
 * That user pulls, hits Merge, get the merge window up
125 48 Chris Cannam
 * Do an "instructor-guided" merge
126 48 Chris Cannam
 * Commit, push, get collaborator to pull
127 48 Chris Cannam
128 48 Chris Cannam
h4. Annotate ("blame")
129 48 Chris Cannam
130 48 Chris Cannam
 * Run annotate on the recipe file to see who changed what and when
131 48 Chris Cannam
132 48 Chris Cannam
h3. Part 4: More sophisticated business at the command-line
133 48 Chris Cannam
134 49 Chris Cannam
h4. @hg archive@: packaging from a tag
135 50 Chris Cannam
136 55 Chris Cannam
Having tagged the version (@v0.1@ or whatever we called it) that we're going to send off to the agent, now we need to pull out _only that version_ and send it off, without the whole repository attached.
137 55 Chris Cannam
138 55 Chris Cannam
 * Open a terminal window
139 55 Chris Cannam
 * @cd@ to the working copy
140 55 Chris Cannam
 * Run @hg archive -r v0.1 book-v0.1.zip@
141 55 Chris Cannam
 * Check @book-v0.1.zip@ and make sure it contains (only) the correct files for revision 0.1
142 55 Chris Cannam
143 49 Chris Cannam
h4. @hg id@: provenance when running experiments
144 50 Chris Cannam
145 1 Chris Cannam
 * Run @hg id@ at command line and note that it shows the id of the current parent revision
146 1 Chris Cannam
 * We can do this from a script when running an experiment, or from a Python program
147 80 Chris Cannam
148 80 Chris Cannam
h4. @hg backout@: undoing an earlier revision
149 80 Chris Cannam
150 80 Chris Cannam
 * Want to undo something we committed earlier? @hg backout@ will prepare a changeset which is the "inverse" of some earlier commit. That might involve resolving a merge, if something else has changed in the mean time. You can then test it and commit.
151 56 Chris Cannam
152 49 Chris Cannam
h4. @hg bisect@: finding the origin of bugs you can't see (analogy with @hg annotate@ for finding bugs you can see)
153 56 Chris Cannam
154 75 Chris Cannam
 * Example based on the Python code from elsewhere in the workshop
155 75 Chris Cannam
156 57 Chris Cannam
h3. Misc notes
157 1 Chris Cannam
 
158 42 Chris Cannam
Things not yet incorporated into the above: Copying, renaming, deleting files; Branching and merging amonst branches; Stuff that is different in other systems
159 1 Chris Cannam
160 76 Chris Cannam
Should we cover (named) branches and merges between them? 
161 31 Chris Cannam
162 1 Chris Cannam
Against: perhaps a level of complication too far for a two-hour intro; Greg doesn't cover them in the Subversion version; lessons learned from Hg are not immediately applicable to git or Subversion because the branching methods are somewhat different.
163 32 Chris Cannam
164 32 Chris Cannam
For: they are much simpler to use in Mercurial than in Subversion!
165 40 Chris Cannam
166 40 Chris Cannam
h2. Quiz
167 40 Chris Cannam
168 54 Chris Cannam
Based on http://software-carpentry.org/4_0/vc/quiz/
169 40 Chris Cannam
170 41 Chris Cannam
 * Why is it a good idea to use version control on your projects?
171 41 Chris Cannam
 * What is a version control repository?
172 41 Chris Cannam
 * Suppose you’ve created a new file on your computer and you want to start using version control for it. How do you go about doing this?
173 41 Chris Cannam
 * Jon is working on a version-controlled project with Ainsley and Tommy. He wakes up early one day, ready to do some work on the project. What is the first thing he should do?
174 41 Chris Cannam
 * Tommy and Jon have up-to-date local repositories, and are both editing a file that contains 10 lines of data. Jon makes a change to the fifth line, and commits and pushes his changes to the remote repository they're both using. Tommy makes a change to the first line of the file, commits his changes, and tries to push them. What will happen, and what should Tommy do next?
175 41 Chris Cannam
 * Ainsley and Jon are up-to-date, and are both editing the sixth line of a file. Jon commits and pushes his changes first. When Ainsley commits and tries to push, what will happen, and what should she do next?
176 41 Chris Cannam
 * How do you undo local changes to files that have not been committed?
177 40 Chris Cannam
 * Give the shell commands you would use to accomplish the following tasks:
178 51 Chris Cannam
 ** Check out the repository located at http://example.com/repo into the directory /cygwin/home/repo
179 51 Chris Cannam
 ** View the log of changes
180 51 Chris Cannam
 ** Add the file “experiment.txt” to the repository
181 51 Chris Cannam
 ** Commit the file to the repository.
182 51 Chris Cannam
 ** Update the local copy to reflect any new changes in the remote repository
183 59 Chris Cannam
184 59 Chris Cannam
h2. Post-presentation notes
185 59 Chris Cannam
186 82 Chris Cannam
"Wrap-up of UCL event":http://software-carpentry.org/2012/05/ucl-bootcamp-version-control-wrap-up/ (first run for this material)