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.

These are some useful recommendations to increase your chances of getting your contributions accepted:

• 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 ["Patch"]es to the ["MailingList"], 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.

• Send only one patch per email, as some review tools and processes assume this.

• Inline ["Patch"]es are preferable to MIME-attached copies of ["Patch"]es, 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 ["Patch"]es, so they will not apply cleanly. This is usually easy to work around, for example by using the patchbomb extension.

• Make sure the ["Patch"]es 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.

  • 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.

Some other useful guidelines:

• 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. 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. It's good to CC -devel, but people are in general more responsive when messages go straight to them.

• 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.