Managing Xen Patches with StGit

How To Generate and Submit a Patch to Xen using StGit

Xen uses Git for its source code management. The current Xen development tree is at http://xenbits.xen.org/gitweb/?p=xen.git;a=summary. Git provides excellent documentation, please read it if this is your first time using Git. Download and install git to your system.

Recommended git extensions

To be able to manage patches better I recommend StGit, which is an application that runs on top of git and provides a functionality similar to Mercurial PatchQueue extension. This tutorial will show how to manage branches with git and StGit, so before proceeding please make sure that StGit is installed.

Generating a patch

---

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

The first thing to do is cloning the xen git repository:

git clone git://xenbits.xen.org/xen.git

This will create a new folder, called xen, where you will work on your patches. We are going to create a branch for each series of patches that we are going to work on. This will allow a developer to work on several patch series at the same time, keeping the patches contained and well classified. Now we will create a new branch on top of the default branch, which is called "master".

stg branch -c my_new_feature

You are now working on a different branch, you can switch back to the "master" branch at any time by using:

stg branch master

Now that we are on the branch we wish to use to develop feature X we will start creating patches. The first thing to do is creating a new patch, StGit will ask for a description of the patch, but if unsure you can leave it blank and fill it later.

stg new first_patch_in_the_series

Here is an example of a simple description:

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>

The first line in the description will be used as the subject when the patch is sent to the mailing list, so please make sure it contains an accurate description about what the patch is expected to introduce. It should be followed by a more accurate description and finally a "Signed-off-by".

Now you can starting modifying the code, all your changes will be contained inside this patch. When finished, you will have to refresh the patch, and create a new one on top if desired.

stg refresh
stg new second_patch_in_the_series

If you want to modify the description of a patch, you should use the edit command:

stg edit first_patch_in_the_series

Also, if you want to move between the series, you can use the following StGit commands, push, pop and goto.

Git format-patch and send-email

The most robust way to send files is by using the git format-patch and send-email commands.

First, we will set up the configuration git send-email will use to send the patches. Edit your ~/.gitconfig file and add the following lines:

[user]
	name = John Smith
	email = john.smith@example.com
[sendemail]
	smtpserver = mail.example.com
	smtpserverport = 25
	smtpuser = johnsmith

Now we can proceed to generate the patches and send them. We will use format-patch to generate the patches and send-email to send them to the mailing list.

git format-patch --subject-prefix="PATCH RFC" -o outgoing/ HEAD~2

The format-patch command allows us to set a prefix to our patch series, in this case I want them to be marked as "RFC", if you don't need to include any specific prefix in the subject you don't need to specify "subject-prefix", and git will use the default one "PATCH X/Y". I've also used the "-o" option so format patch outputs the patches to the "outgoing" folder. Lastly you have to specify the first commit ID that will be used to generate your series. This can either be something like HEAD~3 if your series has 3 patches, and HEAD is the last patch in the series. Alternatively you can also use a commit ID instead of HEAD, and all commits on top of commit ID will be outputted.

Before sending the patches it is recommended that you review them yourself, this can avoid sending patches that contain mistakes that could be avoided, and will allow you to send less revisions. After you have checked that the patches are fine, you can send them using the send-email git command.

git send-email --compose outgoing/*

The "compose" option will allow you to write an introductory email to the series. This is recommended, so the reviewer can understand easily what you are trying to accomplish with this series. Finally git will ask you the mail address where patches should be sent, which the user will have to fill with xen-devel@lists.xen.org.

Common tasks

---

If you are working on a big or controversial patch series, it is very likely that you will have to submit several versions of them, and you will need to rebase your code to match the changes that will be committed to the repository between each revision of your series. You can do that easily with stg rebase. The first step is to update the "master" branch of your repository.

stg branch master
git pull

After that you will need to find the commit ID you want to rebase your series on top of, this can be done using git log. Once you have the commit ID, switch to the branch with your patches and execute:

stg rebase <commit-id>

This will pop all your patches, move the branch to the commit specified and then push your patches again. There's a chance that your patches don't apply cleanly on top of this commit, if this is the case stg will complain loudly, and you will have to manually edit the conflicting file. After editing the file, you can add it to your repository again and continue with the rebase:

git add <conflicting/file>
stg refresh
stg push

stg rebase is really useful, because it allows you to rebase your series on top of any commit, as an example, you can rebase one of your series on top of another, or rebase a series on top of staging changes.