ALPHA version - expect chaos
Useful hints for contributing code to Hedgewars
Updated Mon, 11 Apr 2016 16:03:55 +0100 by sheepluva

Table of Contents


You want to contribute code to Hedgewars? That's great! Here are some hints how to help us with importing your code.

Recommended workflows

Using a mercurial clone


Using (named) branches

Branches are alternative commit histories.

The commits history from one branch, up to any commit, can be merged into other branches when needed. Note: In Mercurial merging a commit always means to also merge all its ancestor commits.

Most main development happens on the main repository branch "default".

We prefer not to use separate branches for little patches, as branches are permanent and will clutter the list of hg branches .

So for small code contributions, use "unnamed branches" instead (see below).

However, if you are going to write code that is more a project than a patch and that will take dozens of commits, feel free to do that work on a new branch.

To create a new branch use hg branch followed by the name of the new branch, before committing the first code.

Using unnamed branches

Unnamed branches a.k.a. topological branches happen when the history of commits within a branch (e.g. "default") splits up into alternative commits chains. These alternative chains will have more than one head (at the the end of each chain) within the same branch, until they will be merged back together into a single chain.

In order for us to be able which bugfixes/features of you we merge into the official repository, you should put each in a separate unnamed branch as described above.

Make sure that the first commit of each bugfix/feature commit set is based on a commit from the official repository, that way your bugfixes/features will not depend on the commits of each other and can be merged into official individually, as needed.

That means: Before you start writing code towards a new bugfix/feature, make sure to hg update -r to a revision from the official repository.

In newer versions of Mercurial you can give those unnamed branches a "local" and removable name using hg bookmark .

You can see example of how unnamed branches and bookmarks are used best HERE

How to export your changes so that we can use them

Public Repository

If you setup a public repository e.g. at github, bitbucket or on your own server, just push your commits there. Then send us the links to the commits/bookmarks that you want to go into the official repository!

Export mercurial commits

With hg export --git -r commitid1 -rcommitid2 ... > my.patch you can export the commits specified to a patch file.

Note: the --git argument is used, so that binary file changes (e.g. changed pictures), are included in the export.

Creating a file containing the code differences

You can use the diff command (if available on your platform) to output the differences between e.g. the original code and yours. Save that into a file and send it to us. Note: Don't forget to also send binary files, so pictures/etc. that you changed - since usually diff will only cover text changes!

If you have a mercurial clone of the official repository but you don't want to locally commit your changes for some reason, you can use use hg diff --git > my.diff to generate a diff file containing changes to code and binary files.

How to ask for patch inclusion in official repository

Just send your patches (or links to them) to [/contact.html /contact.html] the development mailing list]. Feel free to compress them as tar.gz , tar.bz2 or zip .

Don't forget to add a short description (can be a copy of the commit message if it's explaining everything needed).

Note: Please be aware that by sending in patches you grant unC0Rr (the project leader) all rights to the code (and any patents you may hold on it) and assets included in the patch. That implies that your code will be made public under the GNU GPL2.