How To Create and Submit a Patch

Introduction

A patch is exactly what the word says: a small piece of code used to repair a breach. It is normally a plain text file containing only the differences between the current version of the code and the fixed version.

Many people have been submitting patches to the mailing lists and this is a small problem, the patch might be big and sending the patch via mail is not a very good idea. This howto here to remind you not to send the patch via the mailing list but using the tools outside of the mailing lists.

I hope that people will start to give mailing lists a bit more respect and maybe will stop sending patches to the list after reading this.

Generating a Patch

Against Current CVS

The preferred way of creating a patch is to create it against current CVS. The ensures that the patch works with the latest edition of the source code and makes it easier for the developers to apply the patch.

To generate the patch you need to check out a copy of the source code from CVS. More information on how to do this can be found in the CVS HOWTO. After you have made the changes to the source code and made sure it compiles and works as expected, you can create the patch file using the command cvs diff -up > /path/to/patchfile.patch. It is recommended to include the diff -up line in ~/.cvsrc. To summarize the steps:

Check out a copy of the source code from CVS
Apply your changes to the source
Re-compile and make sure it works as expected
Generate the patch file using cvs diff -up > /path/to/patchfile.patch
Examine the resulting .patch file to make sure it contains only the intended changes
Submit the patch using Bugzilla, see below

Against the Latest Release

If you do not have access to CVS you can generate the patch against the latest release.

To generate the patch you will need two copies of the source code: one that is unmodified and one containing your changes to the source. Start by downloading the source code of the latest release, extract it and make a copy of the entire source directory. After you have made your changes to one of the source directories and made sure it compiles and works as expected, you can create the patch file using the command diff -rup /path/to/unmodified/source /path/to/modified/source > /path/to/patchfile.patch. To summarize the steps:

Download the source code of the latest release
Extract the source code
Make a copy of the source code directory
Apply your changes to the copy of the source code
Re-compile and make sure it works as expected
Do a make clean to remove files generated during build
Generate the patch file using diff -rup /path/to/unmodified/source /path/to/modified/source > /path/to/patchfile.patch
Examine the resulting .patch file to make sure it contains only the intended changes
Submit the patch using Bugzilla, see below

Using Bugzilla

Closing a bug patch

The best way to submit a patch to the GIMP development is to send it to Bugzilla and inform the rest of the team what the patch is doing:

Is it closing bugs?
Is it a enhancement?
What are the changes in the code?
Are there any know problems with the patch?

If you have a patch that is closing bugs then you can attach the patch to the bug/bugs explaining what the patch is doing. You can also inform the gimp-devel mailing list about the closed bug but don't attach the patch to the mail sent to the list, instead put the bug links in the mail where the attached patch is located.

Test the patch locally on your own machine and look if it closes the bug there.
Find the bug it is closing in the Open bugs list.
Attach the patch to the bug report.
Explain what the patch is doing and if there might be any problems with the patch.
If you want to send a mail to the gimp-devel list and explain it there also. Remember to have the bug number or even better the link to the bug in the mail. Don't attach the patch to the mail.

Now you just have to wait for the developers and maintainers to look at the patch and see if this is really closing the bug and if it might open new bugs. With a bit of luck it will be implemented in a release done soon either stable or development version.

How about enhancements?

Start a new bug report, mark it as enhancement and put the patch in that report on Bugzilla. This will give developers a good explanation of why you did the patch and how the patch changes GIMP source or adds new things to it. The only thing you need to add to the report is that it is an enhancement and explain the patch a little bit. A simple way to this is to:

Go to Submit a new bug report.
Fire up a new report and select enhancement instead of the others used by normal bug reporting.
Attach the patch and explain what you wanted to get going with the help of this patch.
Remember to explain the purpose of the patch and who might want to use this enhancement.

Thats it! You have done a patch reporting enhancement all that is left is for the developers to look at the report and the patch. They might get even better ideas of how to implement this with the help of the patch you sent.

Remember to

use the same coding style, see file HACKING
never send the patch as a attachment to the mailing lists.
explain what the patch is doing to GIMP.
report the bugs that the patch is closing.
always test the patch before submitting it.
write what version it is tested on. stable? development?