Monday, March 02, 2009

Student's guide on using mercurial - Working outline

We are writing a student guide that will help first year students to deal with the concepts of Version Control Systems. We have chosen mercurial as the tool that we will use for our practical examples since we know how easy and powerful it is.

This user guide will help students from CS programs since at some point they have to deal with versioning control systems in some of their courses and later on when they reach the development world after graduation.

We believe that there is a knowledge gap in our school and learning the concepts and the tools as students will empower us to contribute in a better manner in school and in the real world.

Here is the working outline which we have divided into the theoretical concepts involved and the practical examples. We also see the need to help students not to depend on their schools' infrastructure by giving them tricks on different ways to set their own setups.

By the way, which discussion group would you suggest me to use if I want to ask how you guys use mercurial and how you manage your patches, merges and others?

Let's the learning begin!


  1. Introduction
    Introduce readers to purpose of paper
  2. What version control systems are
    Explain that they are used mainly for source code
    1. File locking and versions merging
      Explain the differences between them. We are going to explain the second one
    2. What a distributed VCS is
    3. Advantages over non-distributed
      Explain the advantages
  3. VCS concepts
    1. Versioning
    2. Diffs
    3. Patches - Reviews
    4. Branching
    5. Merging
  4. Use of VCS in school
    Find what are good reasons to for students to use it
    1. Assignments
      Many students have done collaboratively assignment without VCS
    2. Real world experience
      Explain why using VCS early as a student is helpful to the reality of developers

  1. Work on bugs - Lifecycle of a healthy patch
    Explain few scenarios from developers’ workflow
  2. Mozilla and Seneca’s workflow
    From our experience explain: bugzilla, review process, IRC, pastebin, commit privileges
  3. How to setup your own repositories
    Students should not rely on school to setup infrastructure for you
    1. Free services – github, assembla, Google code
      Explain few of the services available out in there for students to use
    2. Your own Mercurial repositories
      Show how to setup a mercurial repositories with different setups:
      1. on the spot
      2. using school servers
      3. using your home server
  4. Advance work/patch management – Mercurial queues
    This last section will be an external contributed section


  1. I would suggest starting with a real-life scenario where not having version control caused someone to start pulling hair...

  2. I would say add a chapter with comparison/side-by-side using mercurial for existing svn / cvs based project. Like student can host mercurial server locally within a network and use svn and cvs based repository to finally merge changes.

  3. For repository hosting, don't forget to cover Bitbucket. It's a very nice Mercurial-specific hosting provider, with free plans (and free upgrades for OSS stuff), wikis and bug tracking included.

  4. WeirdAl, tell me about it, I had a class mate that wanted to do an assignment by sending emails or by organizing an schedule were not 2 people would work at the same time and that person had already used SVN the previous semester!! It is a good starting point, indeed.

    Jigarsha, what do you mean by ending using svn/cvs to finally merge changes?

    Djc, more than great to know. I have just suggested the rest of the team to eat our own dog food by developing the guide using mercurial. It will be a great practical example.

  5. @armenzg - I think what Jigarsha meant is the case of using Mercurial locally to work on a project that uses a centralised SVN server. Never tried it myself, but I understand it's quite common for people who want the benefits of a DVCS but are working on a project that doesn't support it.

  6. Unless your intent is to make it specific to Mozilla development, I would be weary of using mercurial as an introduction to VCS to people who are unfamiliar with the concept. It adds additional complexity when sometimes you just want people to use VC.

    Fill free to ignore me and prove me wrong though. IMO, subversion wins in the introductory department.

  7. @Cesar - There is a strong trend in the open-source world these days, moving from centralised to distributed systems, and so I don't see a lot of reason to train people in the former model.

    Besides, I don't think SVN is that simple to learn, exactly because it's tied to a central server. Under the distributed model, no remote system is necessary - you can just take your existing workspace, and turn it into a local repository. That's enough to learn the basics of version control; *then* you can introduce the idea of sharing the system with others.

  8. The other day I had to review 8 changesets and what I did is I updated my trees and once on the bus I did "hg serve" and I had the beautiful nice web interface with the diffs and everything easy to look at.

    That feature is a killing machine for me.

    The basic concepts are basically the same in both and students are better off with the basic of the better VCS system

    Unfortunately, I am going to cut off most of the practical part since my prof said is too much of a scope. Once submitted the trimmed version to my prof, we can continue extending the document on a wiki by adding what I removed.

    Thanks all for the input

  9. Hi Nice Blog .I think HR understands the importance of other people tracking time--IT, Lawyers, non-exempt employees, but struggles with the idea of time tracking system .