Contribute using Mercurial

This page is for developers who wish to contribute code to bitfighter.

Bitfighter is now using the mercurial (hg) distributed version control system (DVCS). All history has been imported from subversion (SVN).

Setup

To check out bitfighter you must first download mercurial at:

• http://mercurial.selenic.com/

To get the actual code see the directions on Google Code:

• http://code.google.com/p/bitfighter/source/checkout

For a brief overview of how it differs from SVN, start here:

• http://code.google.com/p/support/wiki/ChoosingAVersionControlSystem

Notes

Some key advantages of mercurial:

1. Distributed development. This brings easier merging and server-side clones for those who wish to contribute.
2. Offline commits.
3. Speed!!! It only took me twelve minutes to push the entire bitfighter repository with all of its history.
4. Compact. Only changesets are transferred instead of entire files.
5. Safety. No more forced merges with conflict resolution.

Usage

An exellent tutorial on mercurial (hg) can be found here: http://hginit.com/

I highly recommend it. You will be an expert and comfortable with hg quickly by reading it.

Taken from the tutorial, the following is a common workflow for hg after you have checked out the code (created a clone):

1. If you haven’t done so in a while, get the latest version that everyone else is working off of:
   • hg pull -u (This is equivalent to running hg pull then hg up)
2. Make some changes
3. Commit them (locally)
4. Repeat steps 2-3 until you’ve got some nice code that you’re willing to inflict on everyone else
5. When you’re ready to share:
   • hg pull to get everyone else’s changes (if there are any)
   • hg merge to merge them into yours
   • test! to make sure the merge didn’t screw anything up
   • hg commit (the merge)
   • hg push

Note: Two steps (hg pull and hg up) are required now for getting the latest code (compare to just svn update.) This is because by default mercurial will not force merges and conflicts on you. When you pull code, you will still be working on your current revision and not the newest code; thus, you must remember to do 'hg up'.

How to contribute code to bitfighter

If you want to help out with bitfighter specifically, then here is a simple workflow:

1. Create a server-side clone for yourself.
   • Go here to create: http://code.google.com/p/bitfighter/source/clones
   • Clone it locally on your computer. hg clone <serversidecloneurl>
2. Pull in the latest changes from the bitfighter default clone
   • hg pull -u https://bitfighter.googlecode.com/hg/
3. Make some changes
4. Commit
5. When you’re ready to share:
   • hg pull https://bitfighter.googlecode.com/hg/ to get any recent changes from the default clone. Note that you do not use the -u flag here: you do not want to immediately update to the latest changes quite yet.
   • hg merge to merge them into your clone
   • test! Make sure the merge didn't break anything
   • hg commit (the merge)
   • hg push to push your contribution back to your server-side clone
6. Contact a developer in charge of the default clone (in this case watusimoto) that you have some nice changes you would like pulled into bitfighter from your clone.

The developer in charge can then do either:

• hg pull <serversidecloneurl> into the default clone
• hg transplant -s <serversidecloneurl> <revision>

Note: If a main developer decides to transplant instead of pull (usually because some of the changes might not be accepted) then you will have to recreate another server side clone to work out of. This is because your clone will be permanently out-of-sync from then on.