SC2012BootcampPlan » History » Version 72

Chris Cannam, 2012-05-01 09:49 AM

1 1 Chris Cannam
h1. Plan for Software Carpentry 2012 Boot Camp 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 43 Chris Cannam
Its goal is to explain version control and introduce Mercurial 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 53 Chris Cannam
 # "Presentation introduction":https://code.soundsoftware.ac.uk/attachments/439/VersionControl.pptx 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
_Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff etc_
45 44 Chris Cannam
46 44 Chris Cannam
 * Go back to that backup file in My Work, add it to ignored list, commit
47 44 Chris Cannam
48 44 Chris Cannam
h4. Managing history
49 44 Chris Cannam
50 44 Chris Cannam
 * The history is not just for information: we can go back to the previous version by updating to it...
51 44 Chris Cannam
 * ... and then a normal update gets us back to the latest version again
52 44 Chris Cannam
53 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).
54 44 Chris Cannam
55 44 Chris Cannam
 * Tag the current revision as v0.1 -- _digression about sensible tag names on whiteboard?_
56 44 Chris Cannam
 * We can now identify this version easily in the history
57 44 Chris Cannam
 * Make and commit another change, this one involving renaming a file
58 44 Chris Cannam
 * What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
59 44 Chris Cannam
60 44 Chris Cannam
Now we have history, but we are still in big trouble if our computer fails. Thus...
61 44 Chris Cannam
62 44 Chris Cannam
h3. Part 2: Working by yourself, but "with backups"
63 44 Chris Cannam
64 48 Chris Cannam
*Topics:* Push, clone, using an online repo hosting service
65 44 Chris Cannam
66 47 Chris Cannam
h4. Pushing local repository to a remote one
67 46 Chris Cannam
68 46 Chris Cannam
 * Register an account on Bitbucket and create a new private repository
69 46 Chris Cannam
 * Look up its URL
70 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
71 46 Chris Cannam
72 47 Chris Cannam
h4. Synchronising new changes
73 46 Chris Cannam
74 46 Chris Cannam
 * Make another change locally, commit (perhaps do this more than once before pushing)
75 46 Chris Cannam
 * Push the change(s), and check the history on site again
76 46 Chris Cannam
77 47 Chris Cannam
h4. Recovering from a disaster
78 46 Chris Cannam
79 46 Chris Cannam
 * Exit EasyMercurial. Delete the local repository / working copy folder completely!
80 46 Chris Cannam
 * Start EasyMercurial again, see that _(sniff)_ the working copy is lost
81 46 Chris Cannam
 * Clone it again from Bitbucket and note that the history is all there
82 46 Chris Cannam
83 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?_
84 1 Chris Cannam
85 48 Chris Cannam
h3. Part 3: Introducing other developers
86 48 Chris Cannam
87 48 Chris Cannam
*Topics:* Conflicts, merges, pull, annotate
88 48 Chris Cannam
89 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).
90 1 Chris Cannam
91 48 Chris Cannam
_Remark: in real-world use, this could very well be the same person just using two different computers_
92 1 Chris Cannam
93 58 Chris Cannam
h4. Getting someone else's changes
94 1 Chris Cannam
95 1 Chris Cannam
 * The second person in the pair should then clone the repository from Bitbucket
96 58 Chris Cannam
 * They should then change something and commit it
97 58 Chris Cannam
 * First person pulls -- notes that there are no changes there (merely committing it doesn't put it on the server)
98 58 Chris Cannam
 * Second person pushes
99 58 Chris Cannam
 * First person pulls again -- the change is now in the history but not in the working copy
100 58 Chris Cannam
 * First person updates -- the change is now in the working copy!
101 58 Chris Cannam
102 58 Chris Cannam
h4. Making alternative versions
103 58 Chris Cannam
104 58 Chris Cannam
 * Both people now make some edits: they should edit _two different_ files and commit them
105 48 Chris Cannam
 * The _second_ user should push their changes to the remote repo first
106 48 Chris Cannam
 * The _first_ user then tries to push. They should get the "Push failed... The local repository may have been changed" message
107 48 Chris Cannam
 * Then the first user pulls instead. (Perhaps checks the Incoming list first?)
108 48 Chris Cannam
 * See that the history graph now shows two heads
109 48 Chris Cannam
110 48 Chris Cannam
_Digression on sociological nature of conflict_ a la Greg if feeling expansive
111 48 Chris Cannam
112 48 Chris Cannam
h4. Merging non-conflicting changes
113 48 Chris Cannam
114 48 Chris Cannam
 * Hit Merge, see that the merge happens straight away
115 48 Chris Cannam
 * Remark that this is the point at which you would now test the merged version
116 48 Chris Cannam
 * Commit, push, get collaborator to pull
117 48 Chris Cannam
118 48 Chris Cannam
h4. Resolving conflicts
119 48 Chris Cannam
120 48 Chris Cannam
 * Get each person to edit the same file, in conflicting ways
121 48 Chris Cannam
 * Again, both users should try to push and the push should fail for the later one
122 48 Chris Cannam
 * That user pulls, hits Merge, get the merge window up
123 48 Chris Cannam
 * Do an "instructor-guided" merge
124 48 Chris Cannam
 * Commit, push, get collaborator to pull
125 48 Chris Cannam
126 48 Chris Cannam
h4. Annotate ("blame")
127 48 Chris Cannam
128 48 Chris Cannam
 * Run annotate on the recipe file to see who changed what and when
129 48 Chris Cannam
130 48 Chris Cannam
h3. Part 4: More sophisticated business at the command-line
131 48 Chris Cannam
132 49 Chris Cannam
h4. @hg archive@: packaging from a tag
133 50 Chris Cannam
134 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.
135 55 Chris Cannam
136 55 Chris Cannam
 * Open a terminal window
137 55 Chris Cannam
 * @cd@ to the working copy
138 55 Chris Cannam
 * Run @hg archive -r v0.1 book-v0.1.zip@
139 55 Chris Cannam
 * Check @book-v0.1.zip@ and make sure it contains (only) the correct files for revision 0.1
140 55 Chris Cannam
141 49 Chris Cannam
h4. @hg id@: provenance when running experiments
142 50 Chris Cannam
143 56 Chris Cannam
 * Run @hg id@ at command line and note that it shows the id of the current parent revision
144 56 Chris Cannam
 * We can do this from a script when running an experiment, or from a Python program
145 56 Chris Cannam
146 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)
147 56 Chris Cannam
148 57 Chris Cannam
h3. Misc notes
149 1 Chris Cannam
 
150 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
151 1 Chris Cannam
152 37 Chris Cannam
Should we cover (named) branches and merges between them? I think yes, if there is time.
153 31 Chris Cannam
154 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.
155 32 Chris Cannam
156 32 Chris Cannam
For: they are much simpler to use in Mercurial than in Subversion!
157 40 Chris Cannam
158 40 Chris Cannam
h2. Quiz
159 40 Chris Cannam
160 54 Chris Cannam
Based on http://software-carpentry.org/4_0/vc/quiz/
161 40 Chris Cannam
162 41 Chris Cannam
 * Why is it a good idea to use version control on your projects?
163 41 Chris Cannam
 * What is a version control repository?
164 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?
165 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?
166 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?
167 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?
168 41 Chris Cannam
 * How do you undo local changes to files that have not been committed?
169 40 Chris Cannam
 * Give the shell commands you would use to accomplish the following tasks:
170 51 Chris Cannam
 ** Check out the repository located at http://example.com/repo into the directory /cygwin/home/repo
171 51 Chris Cannam
 ** View the log of changes
172 51 Chris Cannam
 ** Add the file “experiment.txt” to the repository
173 51 Chris Cannam
 ** Commit the file to the repository.
174 51 Chris Cannam
 ** Update the local copy to reflect any new changes in the remote repository
175 59 Chris Cannam
176 59 Chris Cannam
h2. Post-presentation notes
177 59 Chris Cannam
178 59 Chris Cannam
What did not go well?
179 59 Chris Cannam
180 61 Chris Cannam
 * I found it very difficult to talk loudly and slowly enough and project to the back of the room
181 59 Chris Cannam
 * Several technical problems:
182 59 Chris Cannam
 ** EasyMercurial installation on Linux -- many attendees were using Linux and easyhg (unlike hg) is not in the distro package repos
183 67 Chris Cannam
 ** Recent Ubuntu distro gave "package is of bad quality" error when trying to install the easyhg package -- apparently because the files have the wrong ownership (need to check this)
184 71 Chris Cannam
 ** diff/merge tool not always found correctly (on Linux when installing from source)
185 59 Chris Cannam
 * I forgot to give the intro explaining what we were about to learn -- I explained the advantages of version control but I didn't say "we're using Mercurial, other systems are..." etc
186 72 Chris Cannam
 * I should have explained revision hashes earlier -- i.e. after the very first commit I should have stopped and explained the metadata shown with the commit
187 72 Chris Cannam
 * It would have been useful to stop and stress "now our project is under version control -- this is a result!" as soon as possible
188 68 Chris Cannam
 * I should have shown "backout" and command-line diffs (undoing something later) [and patch?]
189 60 Chris Cannam
 * The "ignore" thing was strangely out of place, better to use an editor that doesn't create backup files in the first place and/or cover that bit later
190 59 Chris Cannam
 * Audience was largely familiar with the command-line -- we were surprised by how familiar -- and might well have responded better to being taught the command-line tool
191 59 Chris Cannam
 * I forgot to give the closing stuff about when you should put something in version control, how often you should commit, etc
192 62 Chris Cannam
 * It complicates things slightly that we have Hg in use for the version control system and then Svn used in provenance section
193 66 Chris Cannam
 * Problems with small screen size:
194 66 Chris Cannam
 ** The Bitbucket site is quite difficult to navigate in a low-resolution projector screen
195 66 Chris Cannam
 ** EasyMercurial's history view doesn't scale as well as it might
196 63 Chris Cannam
197 63 Chris Cannam
What did go well?
198 63 Chris Cannam
199 63 Chris Cannam
 * Fish stew -- everyone has an opinion
200 63 Chris Cannam
 * Merge -- when we actually reached it, (I thought?) it went fairly smoothly
201 69 Chris Cannam
202 69 Chris Cannam
Questions people asked during and after
203 69 Chris Cannam
204 69 Chris Cannam
 * How can I review a merge before the tool automatically applies it (i.e. if it contains no conflicts)?
205 69 Chris Cannam
 * We don't want to use Bitbucket in my institution -- what should we do about hosting repositories ourselves?
206 70 Chris Cannam
 * It would be good to have a handout or something showing the command-line equivalents of the GUI commands