Participating in B3

A quick guide: The proper way to send patches.

Step 1: Get the source code

To get the source code you will need to start your own working copy of the B3 Mercurial repository. This is the most recent copy of the original source code, a development snapshot if you like.

We use Mercurial (hg) not svn! If you don't have Mercurial installed you will need to do that first. Windows users are advised to use TortoiseHg, for it installs Mercurial and a decent GUI to work with.

• Installing Mercurial with TortoiseHg: http://www.selenic.com/mercurial/wiki/index.cgi/TortoiseHg
• General Mercurial Website for other Mercurial installs: http://www.selenic.com/mercurial/wiki/index.cgi/Mercurial

Now you have installed Mercurial you can go ahead and clone our B3 repository. Open a command line prompt where you want to store the code and type:

hg clone http://www.bigbrotherbot.com/mercurial/b3 b3

_{Note: All commandline commands need to be executed from the directory where your repository is located!}

TortoisHg is integrated in Windows File Explorer and right clicking a folder name will present the option to clone a repository.

TortoiseHg > Clone a Repository _{(This format indicates a right click option in Windows Explorer)}

This will download the original code and create a Mercurial working copy on your HD.

Step 2: Working your magic and keeping in sync

Now you have your own copy of the code available you're free to improve the code. Since your working copy is a snapshot with a timestamp, you need to make sure your working copy stays synced with the repository as good as possible. Others might have sent in patches that were imported in the main repository while you were working on your own copy.

SyncEarlySyncOften is the motto and you do it by pulling and updating your working copy each day ;)

Open a command prompt in your working copy main directory and type:

hg pull

and:

hg update

When you've made changes to the code you might need to merge them with the changes you pulled and updated from the main repository. That is done with:

hg merge

In TortoisHg this is done by right clicking the main repository directory. TortoiseHg > Synchronize

And click the Pull button.

Or update directly: TortoiseHg > Update

Conflicts?

When you were modifying code it's possible that the same code in the main repository was changed in the meantime. This creates a conflict upon updating and Mercurial will prompt you to make decisions on what to do. Use common sense and good judgment before going ahead, or if in doubt you can consult us or use the forums to discuss the issue.

Step 3: Satisfied with the tested modifications?

When you're done modifying and testing the results, you will need to commit the changes to your working copy with the commit command:

hg commit

Doing this will create a new revision in the changelog:

hg log

TortoiseHg > View Changelog

The highest number is obviousely the latest revision in your working copy.

Step 4:Creating a patch

Now you've seen the latest revision. Let's say for example it is 13. You now need to create a proper patch file that can be imported in the main repository (if your fix is accepted).

To export the patch info to a filename called changeset_rev13.patch, type this on your command line:

hg export 13 > changeset_rev13.patch

TortoiseHg > View Changelog

Step 5:Sending the patch

The file result can be mailed to bigbrother[at]gmail.com

That's where it starts all over again... And remember: SyncEarlySyncOften