Submitting a Patch using Mercurial

We encourage developers to submit bug fixes and new features back upstream to the official XNAT repository. In this guide, we will go through the process of using Mercurial to submit a patch.

One of the main advantages to Mercurial over older version control systems like CVS, is the ease with which a developer can submit a patch and get it incorporated into the official repository. No longer must the developer email changed files or request SSH access to a server.


This guide assumes that you already have the xdat_core and xdat_release projects checked out, registered in Eclipse, and deployed into Tomcat (shown in the XNAT Eclipse guide).

Making & Submitting a Patch

Make a Change

As an example, let's wrap the SQL created during the update process into a transaction so that if an error occurs the transaction will be rolled back, ensuring that the database is not in a partlally-applied state. In the xdat_core project we modify

We add a BEGIN and COMMIT to the StringBuffer.

Test the Change

Make sure you test your change! In this case, we run the bin/ script and use the newly generated SQL.

Commit the Change

Once we are satisfied that the change works, we can commit the change. In this example we will use the Mercurial Eclipse plugin, but we could just as easily use TortoiseHG or the hg command line tool. We right click on the file and go to Team > Commit ...

A popup will open and we enter a meaningful commit message to indicate what change we made and why we did it.

Submit the Changeset

So far you have commit a change to your local repository. You can now submit the change to the upstream XNAT team in order to get your change included in the official XNAT code. We highly advise that you work with the upstream XNAT developers to benefit everyone who uses XNAT and to ensure that your site's version of XNAT does not significantly diverge from XNAT, thus making upgrades difficult.

There are several methods to submit your changeset: including publishing a fork on or emailing a patch/bundle to the XNAT discussion group. For a discussion on these methods, see Mercurial's Communicating Changes.

In this example, we will create a fork on and issue a pull request.

Making Life Easier for Upstream

Mercurial Queues

Related Pages