Differences between revisions 33 and 34
Revision 33 as of 2010-08-08 19:21:07
Size: 5643
Comment: Advice on description - complete and self-contained, examples are welcome
Revision 34 as of 2010-09-06 12:09:10
Size: 5663
Comment: no trailing period
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
  * Make also sure your ''description starts with a reasonable one-line summary''. The first line should be like ''<command/module/topic>: <short description> (optional issue number)'', no more than 80 characters in total, and followed by an empty line.   * Make also sure your ''description starts with a reasonable one-line summary''. The first line should be like ''<command/module/topic>: <short description> (optional issue number)'', no more than 80 characters in total, no trailing period, and followed by an empty line.

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. The first line should be like <command/module/topic>: <short description> (optional issue number), no more than 80 characters in total, no trailing period, and followed by an empty line.

    • Make sure the description is complete and can be read and understood without following external references and without reading the actual patch. Describe why the patch is needed, what the intent with the patch is, and what the consequence of the patch is. Small examples and tables can be useful.
  • 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. Note that inline patch doesn't mean inline attachment so don't use -i with hg email.

  • 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. To test against main or crew, you can clone these repositories somewhere, run make local inside the repository, and then call the binary hg at the top level of the repository. In Unix you can make a symbolic link from somewhere in your path, such as a location in /usr/local/bin to this binary. For example:

    ln -s /usr/local/src/mercurial/crew/hg /usr/local/bin/hg-crew

    Then you can just invoke hg-crew.

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

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