2010-10-25:

TURNED INTO A BLOG POST:

   http://sagemath.blogspot.com/2010/10/revision-control-and-sage.html


Original rough draft below...

Revision Control and Sage

Target audience: Mathematics researchers

1. Background:

In the 1990s when I first started using revision control, it was a
major, major pain in the arse.  Making a tarball snapshot of the
project directory with a date-stamp was better!  In 2005 when I
started Sage, I didn't know any better, and didn't both with revision
control for the first year.  In 2006, Gonzalo Tornaria told me that
things had improved, and got me to use Darcs.  That lasted just over a
year, when I switched Sage to use Mercurial.  The switch was due to
major headaches installing Darcs (a Haskell program), and Darcs
hanging when our repo got too big and complicated.

We are fortunate that today many difficult problems and decision
decisions for revision control have been addressed through lots of
work.  Revision control is amazingly good now compared to what it was
15 years ago!

RCS, CVS, Subversion, Bitkeeper & Monotone, Darcs, Git/Mercurial/Bazaar

A reference: See
http://hgbook.red-bean.com/read/how-did-we-get-here.html

2. Getting started with HG

 - In sage we use "hg" = (Mercurial).  Why?
   - Because I chose it in early 2007, when Darcs started sucking too much
   - *Distributed* is the way to go these days.  (Modern)
   - Bazaar far too unstable in 2007, to put it mildly.  Bazaar is by
     the people who made Ubuntu.
   - GIT badly documented, too hard to setup, etc... back in 2007.
   ---> so Mercurial was the only choice.  It was just "good enough" at
        the time that we could survive.  Hence Mercurial.

 - hg comes with Sage
   - "sage -hg" 
   - sage: install_scripts command
   - sage: hg_sage.[tab]

 - Or Install: easy to install standalone on OS X, Linux, *and* Windows. 

   - You can do "$ sudo easy_install mercurial" to install systemwide
     the latest version into your default system wide Python.
     It will probably appear in /usr/local/bin/hg

 - Documentation for hg:
   - http://mercurial.selenic.com/
   - http://hgbook.red-bean.com/
   - http://mercurial.selenic.com/learn/
      
3. Project Hosting:

 - If you create your own HG projects, you can easily host them on
   Google Code: http://code.google.com/

   I'm doing this a lot lately with smaller projects:
      - http://code.google.com/p/purplesage/
      - http://code.google.com/p/sagenb/

 - Other systems.  Google code only does HG and Subversion.  
   But there are also similar hosting services for github and bazaar:
      - github: http://github.com/    -- free hosting for git projects
      - Bazaar: https://launchpad.net/

 - Sourceforge: Of course the first major free hosting site is
   sourceforge.net, which offers hosting for all sorts of repos,
   including mercurial.  More general, but not as "clean and focused"
   in abilities as the above.

 - These hosting services are a fairly *new thing* (but not too new);
   all but sourceforge started after Sage.  They provide much, much
   more than just what the revision control systems do; they are more
   than just a place to host your code repository.  They all provide:

      - code hosting (of course)
      - bug tracking
      - code review
      - mailing lists, wiki's, etc. 

   Sage isn't hosted on one of these probably because they are so
   new, and Sage is older.  This may change.   

   Main point: if you want to start a small project with a couple of
   people -- example, writing a research paper -- you can *easily* get
   the full suite of hosting, bug tracking, code review, etc., totally
   for free, backed up, high quality, etc.  Obviously, you are
   trusting your data to either Google, Github, or Canonical, but you
   can easily backup most of it (e.g., the repos, mailing lists).

   They want you to use them:
         "431,000 people hosting over 1,330,000 git repositories"   

   Story: In 2006, when I came to UW, Randy Leveque (a professor in
   applied math) found out about me running the Sage project, and
   wanted to know how to get Mercurial, Wiki's, trac, etc., setup, so
   that he could organize his software development project(s).  I
   explained some basics, and I think he and his students setup
   various project infrastructure, and ran into assorted troubles.
   Today, I would just say "http://code.google.com" (etc.) and be done
   with it!  And Randy would be up and running with more tools than
   listed above in a matter of seconds. 

4. Command line mercurial:

The main point of the rest of this lecture will be about how to use
Mercurial.  It's very hard to beat the official Mercurial Quickstart,
which we'll just go over together in class:

 http://mercurial.selenic.com/quickstart/

    - Make a directory in your computer be under revision control
    - Setup your .hgrc file, if you haven't already.
    - Try cloning a remote repository, e.g., purple sage's
          http://code.google.com/p/purplesage/source/checkout
    - Try committing a change that spans multiple files, so you can
      see that all the changes are together.  Then view the commit via
      "hg serve -p 8200".   

      WARNING: on OS X with the sage-included hg, this "hg serve"
      crashed for me with "Trace/BPT trap" when I visited
      http://localhost:8200.  I opened a trac ticket:

            http://trac.sagemath.org/sage_trac/ticket/10171

      So I did "sudo easy_install mercurial" to get a new version
      systemwide, and now this works for me:
           "/usr/local/bin/hg serve -p 8200" 
      

5. Wednesday and Friday: more advanced stuff

     - branching
     - cloning
     - queues
     - bundles