This page is primarily intended for Mercurial's developers.
How to help us improve Mercurial's code.
1. Submission checklist
Please double-check your patch meets the following guidelines (explained below) before hitting send:
first line of commit message is of the form "topic: uncapitalized, no trailing period"
bugs that are resolved are mentioned in summary in the form "(issueNNNN)" (no space)
patches are sent to the mercurial-devel mailing list (not the BTS)
patch is in the body of the email in the form produced by export for easy review
- all relevant info is in the commit message for posterity (not a "0 of N" message)
patch does just one thing (if you need a bullet list, split your patch)
- patch contains no other gratuitous changes:
- whitespace changes
- code movement
- typo fixes
- string changes
- patch leaves Mercurial in a working state (doesn't depend on future patches)
test suite has been updated and runs cleanly
code passes check-code and matches coding style (no foo_bar variable names!)
relevant help text is updated (see mercurial/help/)
- appropriate branch is indicated in email subject (eg hg email --flag stable)
if a major release code freeze is in effect (see TimeBasedReleasePlan) patches intended for the default branch should not be sent; instead, send them immediately after the release is completed
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 your first submission is not 'minimal', you will probably be sent back here. Save yourself time and start small!
If you're making a large change, we're probably going to want it broken into a series of smaller patches (see OneChangePerPatch). 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:
- implement one clear step in your process
- leave the code in a working state (so bisect always works!)
- include relevant test changes so they're independently testable
- be sent as a separate email
Do not mix formatting changes, organizational changes, or multiple functional changes in the same patch!
Things to consider:
- put the least controversial pieces first - if you're lucky, they'll get applied right away
- the difficulty of reviewing a patch increases rapidly with size - small patches are more likely to get attention
- the probability of a patch getting rejected is also a function of its size - smaller patches mean fewer review round-trips
- bigger patches have more bugs - smaller patches make it easier to locate regressions
3.1. Editing history
You will almost certainly find it necessary to do some form of history editing to generate clean commits, especially after you get your first review feedback. There are multiple tools of varying degrees of power available for this purpose:
commit --amend - modify a head commit's description and contents
rebase - move your commits from one part of history to another, combine commits
mq - manage a stack of changes as patches
histedit - interactively rearrange and modify your commits
evolve - our vision for how history editing should work in the future (experimental)
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!
See our coding style for what we expect code to look like (yes, we're serious about the underscores)
Use contrib/check-code.py to check for common style errors ( python contrib/check-code.py --blame `/usr/bin/hg manifest` )
Add new test cases as needed
Run the test suite to make sure you haven't broken anything
- Patches should apply cleanly against the tip of the appropriate branch (default or stable)
Don't touch the i18n/ directory for code or doc changes (translations is a separate process)
5. Changing C code
Changes involving the C code should be done in a way so that tests will pass across changesets even without recompiling. This is so that, for example, "bisect" can be run without needing to run "make" each time.
A recommended strategy is to add a new interface to the C code when changing behavior (do not change old interfaces), and then in the Python check for the existence of that new interface.
If you change tests that rely on changes to C extensions, make sure you also run the tests in "pure" Python mode (and vice versa), using for example:
$ python run-tests.py --pure
6. 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 ...
- lowercase summary line, no trailing period
- start with the most useful topic keyword (eg command name, subsystem)
- summarize the fix, not the problem
add '(issueNNNN)' if it fixes an issue in the BugTracker (and automatically move the issue to testing)
- use '(BC)' to flag backward compatibility changes, use '(API)' to flag major internal API changes.
- a blank line after the summary
- a more complete description of the problem if necessary
- all lines less than 80 characters
Patch descriptions should be aimed at helping the reviewer understand the issue you're addressing.
Try to use the form "When I tried to do X, I got result Y, but the result should be Z". This is better than "X does not work" which assumes a common understanding of what it means for X to work and leaves the reader to intuit what Y and Z might have been.
Try to answer the following, where appropriate:
- why we need this patch
- how you've implemented it
- why the choices you've made are the right ones
- why the choices you didn't make are the wrong ones
- what all the corner cases are (consider a table!)
- what shortcomings exist
- what file formats and data structures you've used
what compatibility issues exist
- what's missing, if anything
what it looks like, if relevant (include sample output!)
7. Emailing patches
We like to receive changes as patches by email. This allows us to review patches, give feedback, and track which patches need attention.
Patches go to email@example.com - no subscription necessary! (we manually whitelist all legitimate posters)
Patch emails should have [PATCH] in the subject followed by a summary (not included in the patch)
We prefer patches in the message body so we can review them (no attachments or URLs!)
Patches should be in the '# HG changeset patch' form output by 'hg export' - unified diff with author and full patch description
Sending a patch implies granting permission to use it in our project under an appropriate license
- Apple Mail, Gmail and possibly other mail clients corrupt patches when sending them in the body. Using the patchbomb extension always works; see below for details.
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.
7.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 <firstname.lastname@example.org> to = email@example.com [smtp] host = smtp.gmail.com port = 587 tls = starttls username = firstname.lastname@example.org
(See the hgrc manual for more SMTP configuration options).
Then run the following to do a dryrun test:
$ hg email --test <change1> <change2> ...
'--flag' can be used to flag a patch, e.g. "STABLE", "RFC", "v2"
don't use '--inline', it's a weird MIME thing and not what we want
- please don't send a 0 of X summary message, instead put everything relevant in your commit messages for posterity
8. Flow control
A large fraction of patches are reviewed by mpm, who attempts to make sure no submissions fall through the cracks. When he gets backlogged, his time to reply goes up significantly. If you're planning on sending more than a couple patches, it is important to pace your submissions.
The state of mpm's email backlog can be seen here. The first number indicates the number of messages, the second is the number of patches, and the third is the age of the oldest patch in days. If the second number is greater than 100, please have extra patience and send only small sets of patches between replies.
Please also make sure the state of your patches in Patchwork is updated1. This system is strictly secondary to the mailing list, but is helpful to other reviewers for finding patches that still need review.
9. Etiquette and advice
- Try to respond quickly to feedback before we forget what your patch is about
- Tell us everything you want us to know about a patch, every time
- If we ask for fixes, don't send a patch to your patch, send a new fixed patch
Consult 'hg log' to cc: the most relevant developers for the code you're working on
- Consider giving input on other people's patches
Discuss your patches on IRC to get faster review and valuable initial feedback
10. See also
Our compatibility rules for new features
The patchbomb extension automates emailing patches
The MQ extension is handy for managing patch series
How can I make sure the state in patchwork is updated? Could somebody explain please? (1)