Submitting Xen Patches - mercurial

How To Generate and Submit a Patch to Xen using mercurial

Xen now uses git for its source code management, and we encourage everyone to use git. However, we have historically used Mercurial, and still maintain mercurial branches for those who which to continue using mercurial.

The current Xen development tree is at http://xenbits.xen.org/xen-unstable.hg. An excellent tutorial is here. Download and install mercurial to your system.

Generating a patch

---

Here's a recommendation on how to send patches, as suggested by the Xen maintainers.

To begin, configure Mercurial by making the following additions to your ~/.hgrc:

• Enable the Patchqueue extension

[extensions]
mq=

• Show function names in patch hunk headers (which makes patches easier to review).

[diff]
showfunc=True

When you want to make a patch, create a patch on the patch queue:

hg qnew patch01.diff

Then edit the source files you want to change. You can see which files have changed by using hg status.

When you're done editing, save your changes into the patch, and add a description. The easiest way to add a description is to use the -e option to hg qrefresh:

hg qrefresh -e

foobar: Add a new trondle calls

Add a some new trondle calls to the foobar interface to support
the new zot feature.

Signed-off-by: Joe Smith <joe.smith@citrix.com>

Alternately, after refreshing the patch with hg qrefresh, you can edit the files directly in .hg/patches/. Everything above the line starting with diff will be ignored:

foobar: Add a new trondle calls

Add a some new trondle calls to the foobar interface to support
the new zot feature.

Signed-off-by: Joe Smith <joe.smith@citrix.com>

diff -r 63531e640828 tools/libxc/Makefile
--- a/tools/libxc/Makefile	Mon Dec 07 17:01:11 2009 +0000
+++ b/tools/libxc/Makefile	Mon Dec 21 11:45:00 2009 +0000
...

Repeat as necessary for all of your changes

hg qnew patch02.diff

...

Sending the patches to the list

---

Please see the main [Submitting_Xen_Patches Submitting Xen Patches] page for advice and requirements about what to include in the patch, how to format the patch, and so on.

Mercurial Patchbomb Extension

---

The most robust way to send files is by using the Mercurial Patchbomb extension.

To do this, first set up the Patchbomb extension in your .hgrc file:

[extensions]
hgext.patchbomb =

[email]
method = smtp
from = Your Name <your.email@your-domain.com>
cc = your.email@your-domain.com

[smtp]
host = mail.yourdomain.com
port = 25

Then check to make sure you have the right patches to be submitted by using hg out:

$ hg out
comparing with http://hg/xen-unstable.hg
searching for changes
changeset:   21165:2631707c54b3
tag:         qbase
tag:         add-trondle-call.diff
user:        Joe Smith <joe.smith@citrix.com>
date:        Wed Apr 14 11:16:58 2010 +0100
summary:     foobar: Add new trondle calls

...

Next you need to figure out who (if anyone) you should copy the patches to. To do this you should consult the MAINTAINERS file at the top of the Xen source tree. If there is a specific maintainer listed for the area of the code you are modifying then it is best to copy the patches to them. You should always send patches to the xen-devel@lists.xen.org mailing list as well.

Once you're sure you have the proper series of patches and know who you are sending it to then you're ready to use the patchbomb tool:

$ hg email -o --plain --to xen-devel@lists.xen.org --cc the.maintainer@example.com

(The -o option tells patchbomb to submit all outgoing patches; --plain removes the extraneous HG header information from the patches in the e-mails; --to and --cc say who to send the mail to.) It will ask you some questions, like this:

comparing with http://hg/xen-unstable.hg
searching for changes
This patch series consists of 5 patches.

Subject: [PATCH 0 of 5]

Enter in a summary for the entire patch series here, and press enter. You will then be dropped into an editor, to write the text for the patch series intro e-mail.

NB, emacs users: if you're running this from an emacs shell, this can get tricky, since all of the editors it wants to offer you require a terminal. The best option is probably to enable server mode and then set emacs client as the default editor.

Tada! You should shortly see your patch series appear in your inbox, and on the xen-devel mailing list (depending on how you've configured it.)

Other useful options include:

• -n will go through all the motions of preparing the patchbomb, but instead of sending a mail, will just output the mails it would have sent. Useful for testing.
• -d produces a "diffstat", showing lines added and removed for each file. It asks a lot more questions, though.
• -s & --desc allow you to specify a subject line and body respectively for the summary email.
• firstpatch:lastpatch allows you to name a specific range of patches to send and can be used instead of the -o option.

Sending Patches Manually

It is strongly recommended to use the Mercurial patchbomb extension discussed above. However it is possible to send a patch manually using your regular mail client.

You should be aware that many mail clients have a tendency to mangle the whitespace of a patch making it impossible to apply. It is highly recommended to read Linux's email-clients.txt for advice on how to avoid this in popular mail clients.