Diff for "ContributingChanges"

Contributing changes to Mercurial

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 repo (see DeveloperRepos).

These are some useful recommendations to increase your chances of getting your contributions accepted (see also SuccessfulPatch):

• Make sure your description of what the 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 changes as patches to the mailing list, so other people can comment on them and review what you're doing.

• Use hg export or the 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.
  • We prefer inlined patches over attached patches. It allows reviewer to quote the code when commenting on your patch.

• 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 or turning off flowed text in mailers such as Alpine.

• Make sure the patches apply cleanly against the current 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 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 developers 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 a repository over HTTP that contains the changes. With it, Matt only needs to pull from it if he likes the changes.

CategoryContributing CategoryHowTo