Introduction

This document describes the process I use to create and submit patches to the GNU Compiler for Java (GCJ) and the GNU Compiler Collection (GCC). I hope this proves useful to the people who ask “How do I submit a patch?” on the GCJ/GCC mailing lists.

I am fairly sure that the same process would apply equally well to other GNU software projects and quite possibly to other Free software projects.

Requirements

I assume Linux as the development environment - this process also applies to systems that have all the standard UNIX utilities as well as Larry Wall's “patch” program. The “diff” program used here is the GNU diff utility. On Windows, Cygwin and MinGW MSYS satisfy these conditions.

I use a couple of scripts as wrappers around these commands. These are the getdiff.sh script that generates the patch for a single modified file and the makepatch.sh script that uses the getdiff.sh script to create a patch out of multiple modified files. I recommend that you download and put these scripts in your PATH if you wish to avoid having to type tedious command lines every time you create a patch or want review your changes.

Alexandre Oliva has created a few scripts (imaginatively named “CVS Utils”) that are very useful in submitting (and accepting) patches. In particular, I highly recommend that you get “clcleanup” and the “fixpatch” script that it uses and put them in your PATH. You can get these scripts here.

Before You Start

In order to help you understand this process more clearly, let us assume that you wish to change the files “libjava/foo/bar/Snafu.java” and “libjava/wombat.cc” within the GCC sources as a part of your proposed patch.

The very first thing you need to do before you start modifying the sources is to ensure that the source tree is as up to date as is possible for you. For example, you can download the latest GCC snapshot and update your source tree with it.

The next thing you need to do is to back up the files you intend to modify in their respective folders but with a “.orig” suffix. In our example, after you back up, you should have “libjava/foo/bar/Snafu.java.orig” and “libjava/wombat.cc.orig” apart from the original files and identical to them. This step is very important!

Modifying the Sources

Now go ahead and make the changes you intended to make. You will of course have to adhere to the coding standards in effect for that module and/or the programming language. The GNU Coding Standards are pretty detailed and apply strictly to GCC. GCJ has its own addendum for Java source files.

An important thing to note here is that you should use a code editor that does not act too smart with TABs and spaces. You could otherwise end up ruining the formatting of the source code you are modifying.

Testing Your Changes

After this you should do a clean bootstrap build and run the testsuite and any additional tests that you want to run to make sure that your patch really fixes the problem. There should be no regressions as a result of your patch.

Ignore this at your own peril - you really do not want hordes of angry developers with bared fangs crying for your blood if your patch somehow gets accepted and committed to the tree and causes regressions (or worse, build failures).

Once you are satisfied with your changes and have confidence in them, it is time to create a patch that you can submit to the maintainers of the project.

Writing a ChangeLog Entry

You begin by describing your changes in the “ChangeLog” for the affected module.

All modules in almost all the major Free software projects maintain “change logs” that describe the changes that have been made till date to the source tree. These logs comprise entries that have the date on which the change was made/committed, the name of the author of the change, the email address where he/she can be contacted, followed by lines that describe the actual changes. By convention, the active change log is kept in a file named “ChangeLog” in the main folder of a module and the entries are maintained in a reverse chronological order (latest changes first).

You will need to find the appropriate ChangeLog file and add an entry describing your changes. To find this file, look for it in the folder containing the modified source file, if it is not found, in the parent folder of the folder, and so on. In our example, this file can be found in the “libjava” folder. Before you add your entry, back up the original file with a “.orig” extension as before. So you should now have the file “libjava/ChangeLog.orig” that is identical to the original file.

Take a look at the other ChangeLog entries to see how to write one. For our example, the relevant ChangeLog entry could look like this:

2003-07-14  Ranjit Mathew  <rmathew@example.com>
* foo/bar/Snafu.java (getGrok): Use native method
for computing grok.
* wombat.cc (getGrok): New method for computing grok
using get_grok().

The ChangeLog entry header is a line of the format:

The lines following the header describe the affected files and the methods/functions within them that were affected by your change. Note that each such line is preceded by a real TAB character and not an “equivalent” number of spaces. For GNU projects, you can find all you need to know about writing ChangeLog entries here.

If your patch fixes a reported GCC/GCJ bug, be sure to have a line like “Fixes PR c++/7910” as the first line in the ChangeLog entry description.

Creating the Patch

Now you are all set to create the patch. Execute the makepatch.sh script in the root folder of the module, filter its output through the clcleanup script and redirect the final output to a text file.

In other words, for our example, simply execute the following in the “libjava” folder within the GCC source tree:

If you examine “/tmp/mypatch.txt”, it might look something like the following:

Index: ChangeLog
from  Ranjit Mathew  <rmathew@example.com>
* foo/bar/Snafu.java (getGrok): Use native method
for computing grok.
* wombat.cc (getGrok): New method for computing grok
using get_grok().
Index: foo/bar/Snafu.java
===================================================================
--- foo/bar/Snafu.java	Mon Jul 14 07:49:50 2003
+++ foo/bar/Snafu.java	Mon Jul 14 07:50:48 2003
@@ -1,4 +1,6 @@
}
+    public native int getGrok ();
+
public String toString ()
{
Index: wombat.cc
===================================================================
--- wombat.cc	Mon Jul 14 07:54:02 2003
+++ wombat.cc	Mon Jul 14 07:53:34 2003
@@ -1,4 +1,9 @@
}
+    int foo::bar::getGrok (void)
+    {
+      return get_grok ();
+    }
+
get_name (void)
{

Notice that clcleanup script has removed the date from your ChangeLog entry so that the when the maintainer finally applies your patch, the final ChangeLog entry will automagically have the correct date.

Note that the ChangeLog entry must come first in the patch. Most of the times the command given above works just fine in this respect. Just in case it does not, you can arrange to consolidate the individual file changes obtained using the getdiff.sh script manually in the desired order. This is left as an exercise for the reader.

Submitting the Patch

You can now send your patch to the appropriate mailing list. For GCC in general, patches should be sent to gcc-patches@gcc.gnu.org. For GCJ in particular, patches should be sent to java-patches@gcc.gnu.org.

Your mail should describe the problem that your patch is trying to solve in detail. Alternatively you can also point to the appropriate bug report or the thread on a mailing list where the issue was discussed, etc.

Do not send HTML mail! Use only plain-text to send the mail. You should also be aware of any issues that your mail client might have in sending text mail as is without modification. This might make your patch difficult to apply cleanly and might even irritate the maintainers, who after all have volunteered to work on such projects in their free time. For example, Mozilla Messenger supports sending “Format=Flowed” mails and introduces an extra space in lines that start with a space (such lines are very common in diff outputs). Sometimes it is safer to send the patch as an attachment instead of sending it inline.

If there are objections to your patch or if people suggest a better way of achieving the same thing, you might have to repeat the process until your patch is accepted.

If you do not get a response to your patch in a “reasonable” amount of time (say, a week), you can send a “ping” message to the patches mailing list requesting people to take a look at it.