SC2012BootcampPlan » History » Version 80
Version 79 (Chris Cannam, 2012-05-14 08:58 AM) → Version 80/83 (Chris Cannam, 2012-05-14 09:03 AM)
h1. Plan for Software Carpentry 2012 Boot Camps on Version Control
h2. About the session
The session is a two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.
Its goal is to explain version control to researchers who have never used it before, or who want to understand it better.
h2. Outline
The basic plan is:
# "Presentation introduction":https://code.soundsoftware.ac.uk/attachments/443/VersionControlT.pptx to version control in general
# 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
# Closing remarks talking about other tools, other topics of interest etc
h2. Worked example
Preliminary: Check that participants have EasyMercurial installed and working. All of the following exercises will be using EasyMercurial unless it says otherwise.
h3. Part 1: Working by yourself
*Topics:* Initialising a repository, committing files, reading history, looking at diffs, reverting unwanted changes, going back in time to look at old versions
We will be working on a recipe for fish stew for a future recipe book.
h4. Adding your first file
* Make a new directory, create a text file @fishstew.txt@ in it, start adding an ingredients list, save
* Run up EasyMercurial; enter user name and email address
* "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
* Add file: that tells the version control system to keep track of any future changes to it
* Commit: that sets in stone our having added the file. A commit is a checkpoint
* Supply a message, note that we now have some history
h4. Changing things
* Edit the file, change something, save it
* 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)
* Each revision records the state of all files, not just one file: add another file, @omelette.txt@ and add that
* Commit change, note that we now have two revisions
* Review the history and look at the diff
_Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff etc_
* Go back to that backup file in My Work, add it to ignored list, commit
h4. Managing history
* The history is not just for information: we can go back to the previous version by updating to it...
* ... and then a normal update gets us back to the latest version again
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).
* Tag the current revision as v0.1 -- _digression about sensible tag names on whiteboard?_
* We can now identify this version easily in the history
* Make and commit another change, this one involving renaming a file
* What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
Ignoring something we don't want:
* Go back to that backup file in My Work, add it to ignored list, commit
Now we have history, but we are still in big trouble if our computer fails. Thus...
h3. Part 2: Working by yourself, but "with backups"
*Topics:* Push, clone, using an online repo hosting service
h4. Pushing local repository to a remote one
* Register an account on Bitbucket and create a new private repository
* Look up its URL
* In EasyMercurial, hit the Push button, enter URL, push to remote repo, check that the history is present and correct on the site
h4. Synchronising new changes
* Make another change locally, commit (perhaps do this more than once before pushing)
* Push the change(s), and check the history on site again
h4. Recovering from a disaster
* Exit EasyMercurial. Delete the local repository / working copy folder completely!
* Start EasyMercurial again, see that _(sniff)_ the working copy is lost
* Clone it again from Bitbucket and note that the history is all there
_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?_
h3. Part 3: Introducing other developers
*Topics:* Conflicts, merges, pull, annotate
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).
_Remark: in real-world use, this could very well be the same person just using two different computers_
h4. Getting someone else's changes
* The second person in the pair should then clone the repository from Bitbucket
* They should then change something and commit it
* First person pulls -- notes that there are no changes there (merely committing it doesn't put it on the server)
* Second person pushes
* First person pulls again -- the change is now in the history but not in the working copy
* First person updates -- the change is now in the working copy!
h4. Making alternative versions
* Both people now make some edits: they should edit _two different_ files and commit them
* The _second_ user should push their changes to the remote repo first
* The _first_ user then tries to push. They should get the "Push failed... The local repository may have been changed" message
* Then the first user pulls instead. (Perhaps checks the Incoming list first?)
* See that the history graph now shows two heads
_Digression on sociological nature of conflict_ a la Greg if feeling expansive
h4. Merging non-conflicting changes
* Hit Merge, see that the merge happens straight away
* Remark that this is the point at which you would now test the merged version
* Commit, push, get collaborator to pull
h4. Resolving conflicts
* Get each person to edit the same file, in conflicting ways
* Again, both users should try to push and the push should fail for the later one
* That user pulls, hits Merge, get the merge window up
* Do an "instructor-guided" merge
* Commit, push, get collaborator to pull
h4. Annotate ("blame")
* Run annotate on the recipe file to see who changed what and when
h3. Part 4: More sophisticated business at the command-line
h4. @hg archive@: packaging from a tag
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.
* Open a terminal window
* @cd@ to the working copy
* Run @hg archive -r v0.1 book-v0.1.zip@
* Check @book-v0.1.zip@ and make sure it contains (only) the correct files for revision 0.1
h4. @hg id@: provenance when running experiments
* Run @hg id@ at command line and note that it shows the id of the current parent revision
* We can do this from a script when running an experiment, or from a Python program
h4. @hg backout@: undoing an earlier revision
* 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.
h4. @hg bisect@: finding the origin of bugs you can't see (analogy with @hg annotate@ for finding bugs you can see)
* Example based on the Python code from elsewhere in the workshop
h3. Misc notes
Things not yet incorporated into the above: Copying, renaming, deleting files; Branching and merging amonst branches; Stuff that is different in other systems
Should we cover (named) branches and merges between them?
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.
For: they are much simpler to use in Mercurial than in Subversion!
h2. Quiz
Based on http://software-carpentry.org/4_0/vc/quiz/
* Why is it a good idea to use version control on your projects?
* What is a version control repository?
* 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?
* 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?
* 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?
* 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?
* How do you undo local changes to files that have not been committed?
* Give the shell commands you would use to accomplish the following tasks:
** Check out the repository located at http://example.com/repo into the directory /cygwin/home/repo
** View the log of changes
** Add the file “experiment.txt” to the repository
** Commit the file to the repository.
** Update the local copy to reflect any new changes in the remote repository
h2. Post-presentation notes
What did not go well?
* I found it very difficult to talk loudly and slowly enough and project to the back of the room
* Several technical problems:
** EasyMercurial installation on Linux -- many attendees were using Linux and easyhg (unlike hg) is not in the distro package repos
** 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)
** diff/merge tool not always found correctly (on Linux when installing from source)
* 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
* 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
* It would have been useful to stop and stress "now our project is under version control -- this is a result!" as soon as possible
* I should have shown "backout" and command-line diffs (undoing something later) [and patch?]
* 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
* 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
* I forgot to give the closing stuff about when you should put something in version control, how often you should commit, etc
* It complicates things slightly that we have Hg in use for the version control system and then Svn used in provenance section
* Problems with small screen size:
** The Bitbucket site is quite difficult to navigate in a low-resolution projector screen
** EasyMercurial's history view doesn't scale as well as it might
** I generally wasn't practised enough with the screen size and spent too much time hunting for windows and flipping between things
What did go well?
* Fish stew -- everyone has an opinion
* Merge -- when we actually reached it, (I thought?) it went fairly smoothly
Questions people asked during and after
* How can I review a merge before the tool automatically applies it (i.e. if it contains no conflicts)?
* We don't want to use Bitbucket in my institution -- what should we do about hosting repositories ourselves?
* It would be good to have a handout or something showing the command-line equivalents of the GUI commands
h2. About the session
The session is a two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.
Its goal is to explain version control to researchers who have never used it before, or who want to understand it better.
h2. Outline
The basic plan is:
# "Presentation introduction":https://code.soundsoftware.ac.uk/attachments/443/VersionControlT.pptx to version control in general
# 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
# Closing remarks talking about other tools, other topics of interest etc
h2. Worked example
Preliminary: Check that participants have EasyMercurial installed and working. All of the following exercises will be using EasyMercurial unless it says otherwise.
h3. Part 1: Working by yourself
*Topics:* Initialising a repository, committing files, reading history, looking at diffs, reverting unwanted changes, going back in time to look at old versions
We will be working on a recipe for fish stew for a future recipe book.
h4. Adding your first file
* Make a new directory, create a text file @fishstew.txt@ in it, start adding an ingredients list, save
* Run up EasyMercurial; enter user name and email address
* "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
* Add file: that tells the version control system to keep track of any future changes to it
* Commit: that sets in stone our having added the file. A commit is a checkpoint
* Supply a message, note that we now have some history
h4. Changing things
* Edit the file, change something, save it
* 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)
* Each revision records the state of all files, not just one file: add another file, @omelette.txt@ and add that
* Commit change, note that we now have two revisions
* Review the history and look at the diff
_Digression: every action we're taking here corresponds to one command-line command: show hg log, hg diff etc_
* Go back to that backup file in My Work, add it to ignored list, commit
h4. Managing history
* The history is not just for information: we can go back to the previous version by updating to it...
* ... and then a normal update gets us back to the latest version again
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).
* Tag the current revision as v0.1 -- _digression about sensible tag names on whiteboard?_
* We can now identify this version easily in the history
* Make and commit another change, this one involving renaming a file
* What if we make a change and decide we don't want to commit it? Edit something, then hit Revert
Ignoring something we don't want:
* Go back to that backup file in My Work, add it to ignored list, commit
Now we have history, but we are still in big trouble if our computer fails. Thus...
h3. Part 2: Working by yourself, but "with backups"
*Topics:* Push, clone, using an online repo hosting service
h4. Pushing local repository to a remote one
* Register an account on Bitbucket and create a new private repository
* Look up its URL
* In EasyMercurial, hit the Push button, enter URL, push to remote repo, check that the history is present and correct on the site
h4. Synchronising new changes
* Make another change locally, commit (perhaps do this more than once before pushing)
* Push the change(s), and check the history on site again
h4. Recovering from a disaster
* Exit EasyMercurial. Delete the local repository / working copy folder completely!
* Start EasyMercurial again, see that _(sniff)_ the working copy is lost
* Clone it again from Bitbucket and note that the history is all there
_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?_
h3. Part 3: Introducing other developers
*Topics:* Conflicts, merges, pull, annotate
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).
_Remark: in real-world use, this could very well be the same person just using two different computers_
h4. Getting someone else's changes
* The second person in the pair should then clone the repository from Bitbucket
* They should then change something and commit it
* First person pulls -- notes that there are no changes there (merely committing it doesn't put it on the server)
* Second person pushes
* First person pulls again -- the change is now in the history but not in the working copy
* First person updates -- the change is now in the working copy!
h4. Making alternative versions
* Both people now make some edits: they should edit _two different_ files and commit them
* The _second_ user should push their changes to the remote repo first
* The _first_ user then tries to push. They should get the "Push failed... The local repository may have been changed" message
* Then the first user pulls instead. (Perhaps checks the Incoming list first?)
* See that the history graph now shows two heads
_Digression on sociological nature of conflict_ a la Greg if feeling expansive
h4. Merging non-conflicting changes
* Hit Merge, see that the merge happens straight away
* Remark that this is the point at which you would now test the merged version
* Commit, push, get collaborator to pull
h4. Resolving conflicts
* Get each person to edit the same file, in conflicting ways
* Again, both users should try to push and the push should fail for the later one
* That user pulls, hits Merge, get the merge window up
* Do an "instructor-guided" merge
* Commit, push, get collaborator to pull
h4. Annotate ("blame")
* Run annotate on the recipe file to see who changed what and when
h3. Part 4: More sophisticated business at the command-line
h4. @hg archive@: packaging from a tag
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.
* Open a terminal window
* @cd@ to the working copy
* Run @hg archive -r v0.1 book-v0.1.zip@
* Check @book-v0.1.zip@ and make sure it contains (only) the correct files for revision 0.1
h4. @hg id@: provenance when running experiments
* Run @hg id@ at command line and note that it shows the id of the current parent revision
* We can do this from a script when running an experiment, or from a Python program
h4. @hg backout@: undoing an earlier revision
* 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.
h4. @hg bisect@: finding the origin of bugs you can't see (analogy with @hg annotate@ for finding bugs you can see)
* Example based on the Python code from elsewhere in the workshop
h3. Misc notes
Things not yet incorporated into the above: Copying, renaming, deleting files; Branching and merging amonst branches; Stuff that is different in other systems
Should we cover (named) branches and merges between them?
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.
For: they are much simpler to use in Mercurial than in Subversion!
h2. Quiz
Based on http://software-carpentry.org/4_0/vc/quiz/
* Why is it a good idea to use version control on your projects?
* What is a version control repository?
* 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?
* 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?
* 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?
* 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?
* How do you undo local changes to files that have not been committed?
* Give the shell commands you would use to accomplish the following tasks:
** Check out the repository located at http://example.com/repo into the directory /cygwin/home/repo
** View the log of changes
** Add the file “experiment.txt” to the repository
** Commit the file to the repository.
** Update the local copy to reflect any new changes in the remote repository
h2. Post-presentation notes
What did not go well?
* I found it very difficult to talk loudly and slowly enough and project to the back of the room
* Several technical problems:
** EasyMercurial installation on Linux -- many attendees were using Linux and easyhg (unlike hg) is not in the distro package repos
** 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)
** diff/merge tool not always found correctly (on Linux when installing from source)
* 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
* 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
* It would have been useful to stop and stress "now our project is under version control -- this is a result!" as soon as possible
* I should have shown "backout" and command-line diffs (undoing something later) [and patch?]
* 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
* 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
* I forgot to give the closing stuff about when you should put something in version control, how often you should commit, etc
* It complicates things slightly that we have Hg in use for the version control system and then Svn used in provenance section
* Problems with small screen size:
** The Bitbucket site is quite difficult to navigate in a low-resolution projector screen
** EasyMercurial's history view doesn't scale as well as it might
** I generally wasn't practised enough with the screen size and spent too much time hunting for windows and flipping between things
What did go well?
* Fish stew -- everyone has an opinion
* Merge -- when we actually reached it, (I thought?) it went fairly smoothly
Questions people asked during and after
* How can I review a merge before the tool automatically applies it (i.e. if it contains no conflicts)?
* We don't want to use Bitbucket in my institution -- what should we do about hosting repositories ourselves?
* It would be good to have a handout or something showing the command-line equivalents of the GUI commands