Labs/Bespin/DeveloperGuide/UsingMercurial

We have had some pain working with Mercurial, so thought it best to write up the best practices on how to work with it as relating to the Bespin project.

For now I will put up some notes, and then we will groom these more:

Getting Started

Our main code repository is hosted at http://hg.mozilla.org/labs/bespin. You can pull from that by:

Downloading Mercurial
Configuring your environment. For example you will at least want to setup a username. I use:

[ui]
username = Dion Almaer <dion@mozilla.com>

[extensions]
fetch =
hgext.extdiff =

[extdiff]
cmd.opendiff = opendiff-w

[merge-tools]
filemerge.executable = opendiff-w
filemerge.args = $local $other -ancestor $base -merge $output

Setup a bitbucket.org account that you can use as your repository
- clone Bespin from our repo to yours and then checkout THAT repo locally to work on

Read up:
- Mozilla on Mercurial
- Mercurial Definitive Guide

Best Practices

Use "hg fetch"
- You need the "fetch =" line in your config
- It will automatically handle merging, so instead of manually doing hg pull / hg merge, just do hg fetch and let it do its job

Do not use branches
- hg is poor with branches, so we have learned to instead create other cloned repos for large chunks of work, and merge from repo to repo

Look ahead
- You can fetch away at will, but you can also run "hg incoming http://..." to see what would get pulled in. I have sometimes done this to release that there are a bunch of branches in there, and then I change my pull to only pull the tip default branch

Eek, broken! How do I get back!
- If you do a fetch/pull and something messes up (or any operation) you can do a "hg rollback" to revert back

Contributing Back

When you are ready to get code back to the main repo, consider the following:

First, fetch from the main repo and merge the latest with your own code
Test your code (we need automated tests!)
Send us a pull request:
- Update a bug saying "I am ready for a pull on changeset XXXX on my repo at http://bitbucket.org/...."
- Ping us on IRC
- Optionally, you could attach a bundle, but we *much* prefer a pull request