Contributing changes to Mercurial
[:MercurialDevelopmentProcess:Mercurial development process] resembles the one described in ["KernelPractice"]. As most free software projects, contributions and feedback are very welcome and even encouraged, but, to make easier to manage those contributions and keep a clean and maintainable code base, these contributions need to follow a review process before entering the main [:Repository:repo] (see DeveloperRepos).
These are some useful recommendations to increase your chances of getting your contributions accepted:
Make sure your description of what the [:Patch:patch] addresses is complete.
If using hg export, add the description along with the exported patch.
Make also sure your description starts with a reasonable one-line summary.
Send your [:ChangeSet:changes] as patches to the [:MailingList:mailing list], so other people can comment on them and review what you're doing.
Use [:Export:hg export] or the [:PatchbombExtension:patchbomb extension] to create and send patches, where possible.
- This will get your name in the changelog without any extra editing and, with patchbomb, email messages will be nicely formatted.
Send only one patch per email, as some review tools and processes assume this.
Inline patches are preferable to MIME-attached copies of patches, because many mailers cannot quote attachments. Inline patches are thus easier to review. Be warned that many mailers will by default screw up the white space of inline patches, so they will not apply cleanly. This is usually easy to work around, for example by using the patchbomb extension.
Make sure the patches apply cleanly against the current [:Tip:tip] (either the main or crew repositories are ok).
Each patch should make sense in and of itself, and not contain pieces of unrelated stuff that you noticed and decided to fix up.
Follow the prevailing coding style in the code you're modifying, not what you think it ought to be. See [:BasicCodingStyle] for a detailed list.
Patches should not contain tab characters.
Patches should not contain trailing white space.
If you are cleaning up white space, do it in a self-contained patch that contains no functional changes.
Run the [:WritingTests:test suite]. Changes breaking the tests are usually integrated with the changes to fix the tests, so that the test suite will run clean in each revision.
Some other useful guidelines:
Don't feel discouraged if you're asked to do some changes. Even if you feel the requested changes are trivial, the developers could do it themselves or even they are a bit nitpicky, you're the one who can do them more effectively, and this way of working also optimizes the main developers' time.
Always resend the entire patch series, not just the changed patch, when you had to fix something in a patch series. To quote mpm: "In general, assume that I've forgotten everything about your earlier patch."
Don't hesitate to resend your patches or ask for review if no answer comes from the mailing list after a while... people may be busy and your changes may have been overlooked. Contributions are considered very valuable and you can be sure they deserve at least a response. Sometimes this response is just the act of committing your patch to one of the official repos. Scan the emails about new changesets that are sent to the devel list.
It may help to send patches to people directly in addition to the developpers mailing list. Use "hg log" on the appropriate files to see who's been committing a lot to them. That gives you some guidance as to who to send patches to. People are in general more responsive when messages go straight to them instead of via a mailing list. It may also be helpful to have a look at the ["CategoryHomepage"] entries to find the relevant people to contact for a specific subsystem.
Joining the IRC channel (#mercurial on irc.freenode.net) can be an effective way to get faster review and valuable initial feedback. Again, use "hg log" to see whom to chat up.
You could [:Serve:serve] a repository over HTTP that contains the changes. With it, Matt only needs to [:Pull:pull] from it if he likes the changes.