EasyMercurial

h1. Plan for Software Carpentry 2012 Boot Camp on Version Control

h3. Purpose

To explain version control to researchers who have never used it before, or who want to understand it better.

h3. Context

Two hour interactive live workshop, using EasyMercurial and the Mercurial command-line tool.

h2. Outline

The basic plan is:

 # presentation introduction to version control in general (using either whiteboard drawings or a PowerPoint presentation)

 # 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. Contents

Detailed contents:

 * A presentation introduction to the concept of version control.

 ** What is it for and why is it useful?

 ** What can go wrong without it?

 ** How does a version control system work?

 ** *History* + *Collaboration*

 * Check that participants have EasyMercurial installed and working. All of the following exercises will be using EasyMercurial unless it says otherwise

 * *Worked example, part 1: Working by myself*

 ** *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

 ** Make a new directory, create a text file @fishstew.txt@ in it, start adding an ingredients list, save

 ** Run up EasyMercurial, "Open" that directory, see @fishstew.txt@ in untracked file list, explain this

 ** Add file, commit, supply a message, note that we now have some history

 ** 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_

 ** A changeset records the state of all files, not just one file: add another file, @omelette.txt@ and add that

 ** Commit change, review history, 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

 ** 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

 ** 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?_

 ** Make and commit another change, just to make the history more interesting

 ** What if we make a change and decide we don't want to commit it? Edit something, then hit Revert

 ** ... but we are still in big trouble if our computer fails. Thus:

 * *Worked example, part 2: Working by myself "with backups"*

 ** *Topics:* Clone, push and pull, using an online repo

 ** 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

 ** Make another change locally, commit, push, and check the history on site again

 ** 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?_

 * *Worked example, part 3: Introducing other developers*

 ** *Topics:* Conflicts, merges

 ** 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

 ** The second person in the pair should then clone the repository from Bitbucket

 ** Both people can then make some edits: they should edit the same file

 ** 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?) History graph now shows two heads -- _digression on sociological nature of conflict_ a la Greg if feeling expansive

 ** Hit Merge, get the merge window up. Do an "instructor-guided" merge

 ** Commit, push, get collaborator to pull

 ** Run annotate (blame) on the recipe to see who changed what and when

 * *Worked example, part 4: More sophisticated business at the command-line*

 ** @hg archive@: packaging from a tag

 ** @hg id@: provenance when running experiments

 ** @hg bisect@: finding bugs you can't see (analogy with @hg annotate@ for finding bugs you can see)

Things not yet incorporated into the above: Copying and renaming files; Branching and merging amonst branches; Stuff that is different in other systems

Should we cover (named) branches and merges between them? I think yes, if there is time.

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!