Development workflow with mercurial, bitbucket and fabric


I recently read Joel Spolsky's tutorial on Mercurial and thought it was a very nicely done discussion on mercurial and moving from svn to hg. If you have not read it, I encourage you to take a look at it. I'm sure most folks will learn at least a little bit.

As many of you know, Satchmo moved to using Bitbucket and mercurial in June 2009. Now that I've been using it for several months, I thought I'd write some notes on how it's been going and what my workflow looks like. I'm hopeful that this will help people understand how to use the tools better and I also hope it will help people understand better how they can contribute back to Satchmo.

Before I get started, I will make the caveat that pretty much everything I say here applies equally to git and github. I personally believe that the real differences between git and hg are so minor that there's no point in arguing about choosing one over the otger. Both of these dvcs' are head and shoulders above svn, as long as folks make that jump to a dvcs they will reap tons of benefits.

Bitbucket and Mercurial

Normally, I keep one copy of Satchmo that reflects tip on bitbucket. I call it satchmo-gold. I then clone a copy to various working dirs for my local changes. Then, once everything is ready to be pushed to bitbucket, I push to gold, then push to bitbucket. Here's a quick sample of how I do things.

  • Make sure gold is updated:

    ~/src/hg-stuff/satchmo-gold$ hg pull -u
    pulling from ssh://[email protected]/chris1610/satchmo/
    searching for changes
    no changes found
  • Now, make sure my working satchmo has everything updated:

    ~/src/hg-stuff/satchmo-gold$ cd ../satchmo-working
    ~/src/hg-stuff/satchmo-working$ hg pull -u
    pulling from /home/chris/src/hg-stuff/satchmo-gold
    searching for changes
    no changes found
  • Next, make changes in the working directory, test and get ready to deploy them to bitbucket.

    ~/src/hg-stuff/satchmo-working$ hg commit
    ~/src/hg-stuff/satchmo-working$ hg push
    pushing to ~/src/hg-stuff/satchmo-gold
    searching for changes
    adding changesets
    adding manifests
    adding file changes
    added 7 changesets with 6 changes to 3 files
  • The final step is to update satchmo gold and push the changes to bitbucket.

    ~/src/hg-stuff/satchmo-working$ cd ../satchmo-gold
    ~/src/hg-stuff/satchmo-gold$ hg update
    ~/src/hg-stuff/satchmo-gold$ hg push
    pushing to ssh://[email protected]/chris1610/satchmo/
    searching for changes
    remote: adding changesets
    remote: adding manifests
    remote: adding file changes
    remote: added 7 changesets with 6 changes to 3 files
    remote: bb/acl: chris1610 is allowed. accepted payload.
    remote: quota: 21.9 MB in use, 2.5 GB available (0.86% used)

This pretty much shows how I do things to maintain satchmo tip. However, if you have your own fork of Satchmo on bitbucket, you can do the same thing with your forks.

This is all well and fine but the real power of this combination is when I can pull down someone else's fork and merge those changes with Satchmo. The really cool thing is that this maintains all the prior commit comments and links back to the bitbucket individual that made the changes. It's all very slick.

Here's a simple workflow I recently did to merge rctay's fork with Satchmo.

  • Clone the new fork to my hg-stuff directory.

    ~/src/hg-stuff$ hg clone ssh://[email protected]/rctay/satchmo/ rctay-satchmo
  • Pull his changes into my working directory (assuming it's already up to date):

    ~/src/hg-stuff$ cd satchmo-working
    ~/src/hg-stuff/satchmo-working$ hg pull ../rctay-satchmo
    ~/src/hg-stuff/satchmo-working$ hg update
    ~/src/hg-stuff/satchmo-working$ hg merge
    ~/src/hg-stuff/satchmo-working$ hg commit
  • Now, I can push these changes back up to bitbucket just as I did in previous steps.

The nice thing about this setup is that I can now update my rctay branch and merge easily whenever the need arises. I can also maintain all the different forks in one place and keep an eye on any interesting changes. It's all very flexible, powerful and much simpler than doing with svn.

A final note about Fabric

One other deployment tool I've been using is fabric for deploying code and documentation changes to the satchmoproject site. One of the latest changes that rctay's branch made to the documentation is to uses autodoc to more thoroughly document the views. This is really cool but it made it just a bit trickier to build and deploy the docs. Therefore, I decided to use fabric to automate the process so I wouldn't have to try to figure it out every time I wanted to update the docs. The way I figure, the easier it is to deploy, the more likely I will actually do it!

Here is what my looks like:

from fabric.api import *
from fabric import state

state.output['debug'] = True

def production():
    env.hosts = ['']

def build_local_docs():
    with cd('/home/chris/src/hg-stuff/satchmo-working/docs/'):
        local('make clean', capture=False)
        local('make DJANGO_SETTINGS_MODULE=simplestore.settings ROOT_DIR=/path/to/satchmo-working/ html', capture=False)
    with cd('/home/chris/src/hg-stuff/satchmo-working/docs/.build/html'):
        local('tar cvzf docs.tar.gz *')

def deploy_docs():
    put('/home/chris/src/hg-stuff/satchmo-working/docs/.build/html/docs.tar.gz', '/path/to/docs/')
    with cd('/path/to/docs/'):
        sudo('tar -xvzf docs.tar.gz')
        sudo('rm docs.tar.gz')

This allows me to build and deploy my documentation with two commands:

fab build_local_docs
fab production deploy_docs

I hope these notes help everyone out a bit. Mercurial, bitbucket and fabric are really slick tools and have really improved the collaborative nature of the Satchmo development process.

Posted on February 27, 2010 by chris bitbucket django fabric hg satchmo

1 Comment

james commented on March 24, 2010 at 5:48 a.m.:
Hello Very nice article! Why not do it in Bash? Regards


Reply to original: