Differences between revisions 24 and 25
Revision 24 as of 2008-10-05 08:59:43
Size: 4473
Editor: abuehl
Comment: +link to SuccessfulPatch
Revision 25 as of 2009-05-19 19:31:03
Size: 4486
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
[: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). [[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).
Line 6: Line 6:
'''[:SuccessfulPatch]'''): '''[[SuccessfulPatch]]'''):
Line 8: Line 8:
 * '''Make sure your description of what the [:Patch:patch] addresses is complete'''.  * '''Make sure your description of what the [[Patch|patch]] addresses is complete'''.
Line 11: Line 11:
 * '''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.
 * '''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.
Line 16: Line 16:
 * '''Make sure the patches apply cleanly against the current [:Tip:tip]''' (either the main or crew repositories are ok).  * '''Make sure the patches apply cleanly against the current [[Tip|tip]]''' (either the main or crew repositories are ok).
Line 18: Line 18:
 * '''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.  * '''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.
Line 22: Line 22:
 * '''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.  * '''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.
Line 28: Line 28:
 * '''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.  * '''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.
Line 30: Line 30:
 * 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.  * 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.

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.
  • 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 (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 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 a repository over HTTP that contains the changes. With it, Matt only needs to pull from it if he likes the changes.


CategoryContributing CategoryHowTo

ContributingChanges (last edited 2023-04-06 07:59:14 by RaphaelGomes)