Introduction

This page details how to use Mercurial to check out, modify, and submit patches for RawTherapee development. It is not meant as a full Mercurial tutorial, but instead is focused on how it pertains to RawTherapee. Further, it details the procedures for submitting patches for integration with trunk.

Details

Checking Out

(Updated: The staging repository has been deprecated, and all development is now proceeding on trunk.)

To check out RawTherapee, the first step is to get Mercurial. You can get it from http://mercurial.selenic.com for all major platforms. You should also create your Mercurial config file to specify your name and email address.

After you have Mercurial installed, you must first clone the repository. To do this issue one of the commands:

hg clone https://rawtherapee.googlecode.com/hg/ rawtherapee  

Advanced Use If you know what you are doing, you can also do a server-side clone if you have many changes, and you want to have push access to your own repository. If you do this, please email patches@rawtherapee.com with your clone path when you are ready for me to pull from it.

(Note that all these instructions are intended for terminal use. While there may be various GUI tools to work with Mercurial, it is easier and more consistent to use the command line versions. Feel free to adapt these instructions for GUI use.)

This command will create a new directory 'rawtherapee' (or 'rawtherapee-staging'), and clone the existing repository into it.

Updating an existing repository

Once you have already cloned your repository, you should update it on a regular basis (and especially before you prepare a patch for submission). To update your cloned repository, use the command:

hg pull

followed by

hg update

Of course, you must do this from within the directory you already cloned. For those familiar with Subversion, this is equivalent to the command 'svn update'.

Compiling

There are lots of resources already given for information on how to compile. For starters, you should take a look at the Development forum (http://rawtherapee.com/forum/viewforum.php?f=9)

Note that you need GCC-4.4.3 or higher to compile RawTherapee. Using GCC-4.4.2 or lower will result in compilation freezing on rtengine/CMakeFiles/rtengine.dir/bilateral2.cc.o

Preparing a patch for submission

This is the most important part; you have already checked out the source, successfully compiled, and modified the source code to add a feature or fix a bug. To submit a patch for inclusion back into the main repository, please do the following:

• First do a pull operation to make sure your source is up to date.
• Run 'hg status' to show what files have changed. Use 'hg add' to add all the files require for your particular change set.
• Run 'hg commit' to commit your changes. You will be prompted for a commit log message -- this is the message which shows up in the revision history, so it should be clear and concise. (If you want, you can use the -m flag, and provide a comment inline.) Note that committing is one of the places where Mercurial is logically different from Subversion and CVS; with SVN when you commit, it actually submits your changes to the main repository. In Mercurial (as with other distributed repositories), a commit operation will just commit your changes to your local repository; to get the data upstream, you must either push it (if you have commit access upstream) or submit a patch to someone who has commit access.
• To create a patch, you first must find out the changeset ID(s) for the commits you have made locally. (Each commit creates a unique changeset.) To see all outstanding changesets, you can use the command 'hg outgoing'; it will list all the outgoing changesets. For instance, this is the output from my machine after creating a few test files and committing them:

wyatt@Nova:rawtherapee $ hg outgoing
comparing with https://rawtherapee.googlecode.com/hg/
searching for changes
changeset:   32:0b210a00474b
user:        Wyatt Olson <wyatt@example.com>
date:        Wed Apr 21 20:11:38 2010 -0600
summary:     Test commit

changeset:   33:dc304fde4ed7
tag:         tip
user:        Wyatt Olson <wyatt@example.com>
date:        Wed Apr 21 20:17:08 2010 -0600
summary:     Another changeset

• To create a patch, you can now use the 'hg export' command. Export requires a list of changesets to include. Carrying on from the example above, to create a patch for these commits I would type the following:

wyatt@Nova:rawtherapee $ hg export 32:0b210a00474b 33:dc304fde4ed7
# HG changeset patch
# User Wyatt Olson <wyatt@example.com>
# Date 1271902298 21600
# Node ID 0b210a00474b08a9f7d0fa5ce997d5da99ca3fb8
# Parent  965afc81bc91d84d94cd6b2594bf9b47afc7efd7
Test commit

diff -r 965afc81bc91 -r 0b210a00474b test.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test.txt	Wed Apr 21 20:11:38 2010 -0600
@@ -0,0 +1,1 @@
+This is a test file for Mercurial tutorial
diff -r 965afc81bc91 -r 0b210a00474b tools/test.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/test.txt	Wed Apr 21 20:11:38 2010 -0600
@@ -0,0 +1,1 @@
+Testing 1, 2, 3
# HG changeset patch
# User Wyatt Olson <wyatt@example.com>
# Date 1271902628 21600
# Node ID dc304fde4ed7140554dd7f7ba5ff3c7798464cdb
# Parent  0b210a00474b08a9f7d0fa5ce997d5da99ca3fb8
Another changeset

diff -r 0b210a00474b -r dc304fde4ed7 test2.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test2.txt	Wed Apr 21 20:17:08 2010 -0600
@@ -0,0 +1,1 @@
+Testing 4, 5, 6

It is recommended that you use console redirection to create a single file, rather than just copying / pasting the above output. For instance, on Unix compatible systems:

hg export 32:0b210a00474b 33:dc304fde4ed7 > patch.diff

will create a file 'patch.diff' with the contents of the export. This file is the patch which will be submitted. (I don't know how to do console redirection in Windows; I'm sure there is a similar method for doing this on Windows, but I don't know what it is; if you know feel free to let me know.)

How to submit patches

Once you have your patch, you need to get it submitted for integration into the main repository. The best way is to add the patch to the appropriate item in the Issues list (http://code.google.com/p/rawtherapee/issues/list). If there is not an issue open already (for instance, for an enhancement you did all by yourself), please open a new ticket. By opening a ticket there will be a record of the change, comments and discussion around it, and verification of when it gets added to the repository.

Another method of submitting patches is to send them to patches@rawtherapee.com. Either way will work fine, although it is nice to have the comments and discussion which the issue tracker can provide.

(Advanced) Alternative to Sending Patches

As mentioned above, if you know what you are doing you can create a server-side clone of RawTherapee, and do all your development there. When you are ready to send your commits, you can email patches@rawtherapee.com or submit a new ticket.

Closing Remarks

I hope that this tutorial has helped you start RawTherapee development. For more information on Mercurial, please visit the Mercurial guide at http://mercurial.selenic.com/guide/ . If you feel that any parts of this tutorial are incorrect or unclear, feel free to suggest a change to me.