In Short

If you are a programmer, you are invited to download the source code and to try fixing your favourite bugs - adding the new features you want to have, or ones suggested in the bugtracker. Shoebot's code is small and readable, so it's really simple to get your Python-fu going and start hacking!

Shoebot uses Mercurial for version control, so it will be a lot easier to merge your code if you use it too! It's as simple as cloning the main Shoebot repository and hack on your local copy. When you have some code to contribute back to the project, create an account with http://www.freehg.org and make a public Mercurial repository there of your branch. Then post the URL to the mailing list (or to the comment of a bug, so it can be closed) and the Shoebot maintainer Ricardo will integrate your changes to the Shoebot core.

In Detail

ShoeBot's version tracking is done by Mercurial (hg - the atomic abbreviation for that strange metal :-) Mercurial is a decentralised version control system (VCS). What sets it apart from other VCS such as Subversion or CVS is that there is no central "master" server to hold the project; when you clone a Mercurial repository, you get the exact same tree and files that are available in the 'main' Shoebot branch. This means that your repository is essentially a Shoebot fork. But the Mercurial program allows us to merge two or more forks easily, so this isn't a problem.

In fact, it is a big advantage for quick development: We can all work on different parts of the program and then merge all our changes with little hard work. It is even easier than creating patch files - if you have your Shoebot repository somewhere on the web, Ricardo can easily review your changes and merge them into the main Shoebot tree. And that is why we call each developer's version a "branch" rather than a "fork."

After installing Mercurial, you'll want to have the latest version of Shoebot to work on. For this, you 'clone' the main repository (in SVN terms, do a checkout):

    hg clone https://code.goto10.org/hg/shoebot

If you're working on your branch, there is a Mercurial command for updating your copy with the latest updates from the main tree:

    hg pull

This will update your code with all the new stuff in the main tree, and keep all your changes intact. If you have changed something that has also been changed in the main tree, that is a "conflict," and in that case you'll have to manually merge the changes. For this, you might want the 'kdiff3' tool -- a nice graphical app for checking and merging differences.

So, if you want to do some changes, clone the main tree and work on your local copy. You might want to have a pristine copy of the main tree available and then different clones for different features you want to implement. Just copy the "shoebot" directory that you download and rename it to "shoebot-feature_name". When you're done with a particular feature or bugfix, just merge it back into your local copy of the main tree:

    hg push /path/to/your/original/copy

Then to publish on the web at the FreeHG site:

    hg push http://freehg.org/u/username/shoebot

Be sure to use a clone of the Shoebot repo instead of creating a new repo and copying the Shoebot files there -- that way, we would have to manually merge your changes.

Step By Step Commands

First you get a local copy of the official Shoebot repository:

    hg clone https://code.goto10.org/hg/shoebot

This will create the "shoebot" directory in the current directory, and all the following commands should be run from within this:

    cd shoebot

Then, you make a change as you like, with your preferred code editor. When you are finished making the change and have tested it, you 'commit' the changes. This means you can easily go back to that particular stage if you want to revert, because that version of the project is saved. You can also easily compare versions from commit to commit - like the history of a Wikipedia article. To do this, run the following command, which includes a message describing your changes:

    hg commit -m "My changes were this and that"

An alternative way to handle commits is to install 'qct', a GUI commit tool that makes this task straightforward.

Before uploading your version, you will want to integrate the latest changes from the official repository to your local repository, so that you're always up to date with the newest stuff:

    hg pull https://code.goto10.org/hg/shoebot

When you are ready to publish your new version of Shoebot, visit http://www.freehg.org and create an account (say, 'username') and a repository (say, 'shoebot'). Then to publish there, run these commands:

    hg push http://freehg.org/u/username/shoebot

You can add the FreeHG server information to the hgrc file which sits inside the '.hg' directory in your project's directory.

    gedit .hg/hgrc

Just add the following:

    [paths]
    default-push: http://freehg.org/u/username/yourname-shoebot

Then you'll only need to type this short command to update the published version:

    hg push

If this was unclear, there are also step-by-step instructions for newbies :-)