Creating a patch to submit (Patch Tracker)

Introduction

Do you want to contribute to Code::Blocks? - Thank you! That is really appreciated. Hence you can help us even more if you read the following paragraphs carefully.

First of all please make sure the feature you are implementing is not already implemented in the nightly builds of Code::Blocks. Furthermore browse through the list of available patches at the Code::Blocks project page at SourceForge (see section "Patch submission" below on how to gain access). If you are unsure, don't hesitate to ask in the forum for advice.

You can make it easier for the developers to integrate your patches if you follow the advices of this page. Patches can be created in different formats. The format that is used by Code::Blocks is called a "unified diff". Hence 3rd party tools may still create a different patch format although it may be labelled as "unified diff". To avoid unnecessary incompatibilities the best way to provide a patch is to use the Subversion (SVN) diff (using the command line tool or a SVN GUI application).

What is required?

Not too much, you might already have the required tools installed. You'll need a subversion client software. You can download a current version for your OS at the Subversion project webpage here: http://subversion.tigris.org. If you want to apply or test your patches you'll also need either svn version ≥ 1.7.0 or the patch program; you can download patch and find more information about it at the GNU patch website.

It is a good idea to apply your code to the most up-to-date sources of Code::Blocks as they are available at the SVN repository. You'll find the instructions how to obtain the sources here. Once you've created your local sandbox you can start integrating your changes into it. Thus you may modify existing files or add new ones. When you have finished please make sure you've verified your implementation (feature(s)) work properly. Now it's time to create the patch.

Patch creation

If you have added new files you first have to register them with your sandbox. Thus go into the directory you've added new files and type at the command line:

svn add filename(s)

...whereas "filename(s)" needs to be replaced with the files you've added. Of course if you are not using the command line version of SVN you can easily use the "Add" feature of your prefered SVN GUI. If you've completed adding all your new files to your sandbox you are ready to create the patch.

First of all go to the top-level directory of your sandbox (the first directory that has a hidden ".svn" folder with content). This is done because the patch file generated by the following command is relative to the directory where it's performed. This is the command to create the patch file:

svn diff > my.patch

You can change the name of the patch (my.patch in the example) with a more descriptive name but make sure you leave the file extension ".patch" as this avoids conflicts while submitting the patch. The creation of the difference file (the patch file) may take some time, please be patient.

Once the patch file is created please make sure it contains content! Otherwise make sure you followed the steps above or ask in the development forum for support.

Note: if the created patch is much larger than expected (it should be similar in size to the amount of code you changed/added) it is likely that extraneous white space changes are being picked up. In this case, please use the following command to create the patch file:

svn diff -x -w > my.patch

Note: if you use Powershell on Windows, the generated file can not be used directly because it will be in UTF-16 format. Use Notepad++ to reencode in ANSI or generate it again using this command:

svn diff | out-file -encoding ascii my.patch

If you are using git or git-svn and sending to someone with an svn setup, the output can be more easily handled following these steps or one of the following commands:

git diff --no-prefix > my.patch

svn patch my.patch --strip 1

Patch application and testing

Most Subversion front-end UI tools (like TortoiseSVN or SmartSVN) have an option to apply this patch files directly.

If you are using svn version ≥ 1.7.0, the command:

svn patch my.patch

...will perform some checks and then will patch your files using the difference information saved in the patch file (my.patch in the example).

If you only need the command line without SVN tooling (why would you do so?), then in order to apply a patch you need the patch program (Windows Linux). Make sure you are in the same directory the patch was created and then type the following command:

patch --unified --strip=0 --forward --input=my.patch

Important note: If you are working under Windows you may have to convert the patch file to DOS line-ending format. You can do that using "unix2dos my.patch".

Patch submission

By now you are ready to submit your work to the Patch Tracker at Tickets - the developer platform for Code::Blocks. If you haven't done so already, you need to register with Sourceforge to gain the right to submit patches to projects. The membership is free and appreciated. Select the "Tickets" section (Tickets) of the Code::Blocks project page. Click on "Submit A Patch" and fill out the form that appears. For now you only need to select a category for your patch, a descriptive summary and the patch itself. Make sure you enable the checkbox "Upload Patch" and provide the patch file you've just created. Then you are ready for submission - click on the "Submit patch" button on the bottom of the page.

You should now see the current list of patches with your patch at the top. Please note you can add additional comments or updates to your patch by simply clicking on the patch in the list and fill out the form that appears.

Thank you very much for your submission!