Contributing Changes

How to help us improve Mercurial's code.

/!\ This page is intended for (aspiring) developers.

1. Submission checklist

Please double-check your patch meets the following guidelines (explained below) before hitting send:

2. Getting started

Start by cloning a copy of Mercurial's main repo:

hg clone http://selenic.com/hg

You'll also want to read the following pages:

Other pages you may find important:

3. Organizing patches

If you're making a large change, we're probably going to want it broken into a series of smaller patches. This makes for easier review and tests both for us and for you. This can be tricky at first and you might find tools like MQ and record useful in this process.

Each patch in a series should:

<!> Do not mix formatting changes, organizational changes, or multiple functional changes in the same patch!

Things to consider:

4. Coding style and testing

<!> If you send a patch with an underscore in a variable name, we'll know you haven't read this page!

5. Patch descriptions

It's important that you describe your patch. Patch descriptions should be in the following format:

opener: check hardlink count reporting (issue1866)

The Linux CIFS kernel driver (even in 2.6.36) suffers from a hardlink
count blindness bug (lstat() returning 1 in st_nlink when it is expected
to return >1), which causes repository corruption if Mercurial running
...

Patch descriptions should be aimed at helping the reviewer understand the issue you're addressing. Try to answer the following, where appropriate:

6. Emailing patches

/!\ Don't send your patch to the BugTracker - it can't be reviewed there, so it won't go anywhere!

We like to receive changes as patches by email. This allows us to review patches, give feedback, and track which patches need attention.

Because this is a community project and our developers are very busy, patches will sometimes fall through the cracks. If you've gotten no response to your patch after a few days, feel free to resend it.

6.1. Mailer issues and patchbomb

As mentioned above, patches should be included in the body of emails to make it easy for developers to review and apply your patches. Some mailers make this difficult by mangling the whitespace in patches or similar. If you have trouble sending clean patches or are sending more than a couple patches, you should probably set up the patchbomb extensions which automates the process.

Add something like the following to your .hgrc:

[extensions]
patchbomb=

[email]
method = smtp
from = Ada Lovelace <adalovelace@gmail.com>
to = mercurial-devel@selenic.com

[smtp]
host = smtp.gmail.com
port = 587
tls = starttls
username = adalovelace@gmail.com

(See the hgrc manual for more SMTP configuration options).

Then run the following to do a dryrun test:

$ hg email --test <change1> <change2> ...

Notable options:

7. Etiquette and advice

8. See also


CategoryDeveloper