Submitting Patches

When you are first starting, patches are the best way to send your code contributions to the GNOME project. This page explains how to create a patch. Following these guidelines will not only minimize the work for the maintainers, but also increase the chance of your patch being accepted. The guidelines on this page are generic and should more or less apply to every module; however, make sure to always follow any additional guidelines specified in the HACKING and README files included with the module you are working on.

Getting development code, making changes and producing patches all uses the Git Version Control System. For a detailed guide to using Git in GNOME, see the Git for GNOME developers guide. Make sure that you have followed the Git setup procedure before attempting to use it to create a patch.

1. Get the Code

The recommended way to get the latest development code is through JHBuild. See the GNOME Love introduction to JHBuild. This will clone the relevant Git repositories so that you can work on the code locally.

Alternatively, you can use Git to manually clone the module that you are interested in:

$ git clone git://git.gnome.org/<module name>

2. Make Your Changes

If you're working on an existing bug, it is often worth adding a comment to the bug that you are working on it, if you expect the work to take some time.

Hack hack hack...

3. Commit

Once you have made your changes, create a commit:

$ git commit -a

Here, the -a (meaning all) option includes all the changes you have made to the code in the new commit. You can also be more selective about what you include - the full guidelines contain details. The git commit command takes you to an editor where you can write a commit message.

Your commit message should follow a standard format: a short title, followed by a longer explanation, followed by a link to the relevant bug. Your commit message should look something like this:

Short title describing your change

Longer description and explanation, if necessary. You might need to
explain why you made the changes in the way that you did, for 
example.

Bugzilla link

Here is an example of a good commit message (the first three lines are generated automatically):

commit d2ca14c270a8a0c01d8a897fad4ea2a9c2e31105
Author: Marc-André Lureau <marcandre.lureau@redhat.com>
Date:   Sun Jul 17 21:18:04 2011 +0200

    Add G_VALUE_INIT
    
    The implementation of GValue is not public or documented.  When
    allocated on the stack, initializing a GValue is usually done as
    documented with:
    
    GValue value = { 0, };
    
    There is lot code around (including WebKit) that added all the missing
    fields, resulting in this ugly and non-obvious:
    
    GValue value = { 0, { { 0 } } };
    
    However, this doesn't play nice with -Wmissing-field-initializers for
    example. Thus, G_VALUE_INIT.
    
    http://bugzilla.gnome.org/show_bug.cgi?id=654793

The commit message is good because it:

Has a concise summary of what the change is as the first line
Says why the change was made (avoid a gcc warning)
Gives a real-world concrete example of an affected codebase (WebKit)

4. Create the Patch

This command creates a patch from your last commit:

$ git format-patch HEAD^

5. Submit

Send the patch to the project by attaching it to the relevant bug report in GNOME Bugzilla. Unless explicitly stated in the HACKING file, do not send the patches privately to the maintainer.

6. Follow Up on the Feedback

Your patch will likely go through several iterations of patch review. Wait to get comments about how you can improve the patch, and then make modifications if they are necessary. Then create a new patch and attach it to the bug. This kind of review process is standard practice within GNOME and helps to ensure that our code is all high-quality. Once your patch looks good, the reviewer will merge it in!

Tips

In your commit messages, describe both what the patch does and how it does it, unless the patch is trivial.
Strictly follow the coding style used in the code you are working on. This may sound trivial, but consistency is very important. Many projects describe the preferred coding style in the HACKING file; for other projects just take a look at the surrounding code and try to use the same format.
Avoid unrelated changes. This makes the patch easier to read and approve.
Provide one patch per issue - Do not make big patches that fix unrelated bugs.
Make sure the patch does not contain trailing whitespace and spurious empty lines. You can use git diff --check for this
Do not compress the patch with gzip or similar tools, since it makes reviewing more painful. If the patch is big enough to really require compression, chances are that you need to carefully discuss your patch with the maintainer anyway.

CategoryDeveloperTutorial

live.gnome.org