Contributing Patches

From Cluster Labs

Pacemaker uses the Mercurial revision control system for source code management. If you would like to contribute a bug fix or new feature, you are highly encouraged to submit your patch in a format that Mercurial can easily import. Don't despair -- it's actually quite easy.

Mercurial primer

Mercurial is a distributed, lightweight, open source revision control system that allows for decentralized development. If you are a Mercurial newbie, then the Tutorial is an excellent starting point. For more in-depth information, dig deep into Mercurial: The Definitive Guide.

Mercurial repositories used by Pacemaker

Code that is part of or related to Pacemaker is spread out over a handful of distinct Mercurial repositories:

Please note: the OpenAIS cluster stack, the preferred cluster stack for Pacemaker, does not use Mercurial, nor is it hosted on the Linux-HA or Clusterlabs server infrastructure. If you wish to contribute patches to OpenAIS, please refer to the Developers page on the OpenAIS Wiki.

Setting Mercurial preferences

User-level preferences for Mercurial live in a file named .hgrc in your home directory. You may want to set your preferences similar to this:

[ui]
username = J. Random Hacker <jrh@example.com>
 
[extensions]
hgext.mq=
hgext.patchbomb=
hgext.hgk=
 
[email]
from = J. Random Hacker <jrh@example.com>
bcc = J. Random Hacker <jrh@example.com>
method = smtp
 
[smtp]
host = mail.example.com
username = jrh
tls = true

These preferences will enable you to submit patches via the Patchbomb extension, using SMTP securely via TLS. They will also enable Mercurial Queues, described below.

Cloning a Mercurial repository

To create a local copy of a Mercurial repository, issue the following command in a directory set aside for this purpose:

 hg clone http://hg.clusterlabs.org/pacemaker/stable-1.0 pacemaker-stable-1.0
 cd pacemaker-stable-1.0
 hg update -C tip

Creating and submitting patches

Creating a single patch

If you are creating a one-off patch, such as a simple bug fix, you can simply edit the affected file (or files), compile and test, and then commit the patch locally using the following command:

hg commit

To just commit changes to some specific files, you can also use

hg commit filename filename ...

Regardless of the command used, please be sure to add a meaningful commit message. It should state the purpose of the patch, and include a brief description. This will help the reviewer understand what your patch does, and more importantly, why you chose to do certain things one way and not another.

Now, to submit your patch for review on the appropriate mailing list, issue

hg email -o -t mailing list address

Creating a series of patches

When you make several changes at once, then please do not roll them all into one patch -- this tends to make the review process more difficult than it should be. Instead, split your patch into easily digestible parts. A very convenient way of doing so is to use Mercurial Queues.

To use queues, you must first initialize the repository for doing so:

hg qinit

Then, you may create named patches. The following command will create a patch named "foo", and open up an editor so you can enter a patch description. Again, as with a one-off patch, please enter a meaningful description of the purpose and intention of your patch.

hg qnew -e foo

You can create multiple named patches in one queue, push and pop them around. Please see the Queues Tutorial for more information. Most likely, the command you will be using most often, after you make modifications and want to import them into your patch queue, is this:

hg qrefresh

Finally, after you have tested your patch and are ready to submit it for review, you can again do so by email. To submit a series of patches in your queue containing the patches named foo, bar, and baz, issue the following command:

hg email -t mailing list address foo bar baz

Please be sure to also include a description of the patch series as a whole.