Contribute/Send Patches

This tutorial shows how to send modifications of code in the right way: by using patches.

Notation

The word developer is used here for someone having a KDE Identity account.

Preliminaries

We suppose that you have modified some code in KDE and that you are ready to share it. First a few important points:

• You must allow that the modification will have the license of the file where the modification is made.
• Please make sure that the code compiles correctly on a (fairly) recent version of the software.

What Is a Patch?

Now you have the modification as a source file. Sending the source file will not be helpful, as probably someone else has done other modifications to the original file in the meantime. So your modified file could not replace it.

That is why patches exist. Patches list the modifications, the line numbers and a few other useful information to be able to put that patch back into the existing code. (This process is called "patching" or also "applying a patch.")

Phabricator

Most KDE projects are switching to Phabricator for project management and review. Here you can upload a patch and request the KDE project team or individual maintainer review your code. The Review Board provides tools for viewing diffs online, noting comments against code that needs changes, and granting approval to commit. It is far easier to manage patches using Review Board than using e-mail or Bugzilla, so it is the recommended method to use.

The older way of submitting patches is KDE's Review Board. Most projects that are using Phabricator will prefer you upload your patches there. However many projects have not yet switched, so if you cannot find the repository on Phab, you should check RB. You will use the same KDE Identity to log in to either system.

Creating patches with git

The program git, which is used on the command line interact with the Git repository, has a diff function: git diff. You can run it like this and it will give you the difference of the current directory and all sub-directories below it. Of course, you want to redirect the output to a file:

git diff > ~/patch.diff

There are useful variants too (shown here without redirection):

• For just one file: git diff source.cpp
• For the current directory only: git diff .

Note: even if git can make the difference of another directory (git diff mydirectory), it is not recommended to do it for a patch that should be applied again. (The problem is that the person that will apply the patch will have to be more careful about how he or she applies it.)

Note: for simple diff, like those shown in the examples above, git diff can be used offline, therefore without an active connection to the KDE Git servers.

New Files

First, you need to make Git aware of files you have added.

git add path/to/new/file /path/to/another/new/file

Then, "git status" will show you that the file has indeed been added to the repository.

To add new files to the patch issue:

git diff --staged >> ~/patch.diff

Creating patches without git

The main tool for creating patches is a tool called diff, which makes the difference between two files. This tool has a mode called unified diff, which KDE developers use. Unified diffs have not just the difference between the file but also the neighborhood around the differences. That allows to patch even if the line numbers are not the same anymore.

The most simple patch is created between the modified file (here called source.cpp) and the non-modified version of the file (here called source.cpp.orig.)

diff -u -p source.cpp.orig source.cpp

That lists the difference between the two files in the unified diff format (and with function name information if possible.) However it only displays it to screen, which is of course not the goal. So you need to redirect the output.

diff -u -p source.cpp.orig source.cpp > ~/patch.diff

~/patch.diff is here an example and you can create the file where you prefer with the name that you prefer. (You will soon find out that it is probably not a good idea to create a patch where the source is.)

Non-Text Files

The procedures described above work very well with text files, for example C++ source code. However they do not work with binary files, as diff is not made to handle them. And even if Git can internally store binary differences, git diff is not prepared to do anything similar yet, mainly because it currently uses the unified diff format only, which is not meant for binary data.

Therefore, unfortunately, there is little choice but to attach binary files separately from the patch.

Patches for KDE Bugs

If your patch fixes a bug recorded on bugs.kde.org, please don't forget to add the bug number to your merge request on Review Board.

If you know exactly which developer will process the patch and that you know or that you suppose that he or she currently has time, then you can include this developer in your review request.

And Now?

Now you have to wait that a developer reacts on your patch. (If you are not subscribed to the mailing lists where you have sent the patch, then monitor the mailing list archives] for such a message.)

The reaction is normally one of the following:

• No developer answers. (That is unfortunately happening from time to time.)
• The developer does not want your patch, as he or she is working on the same code.
• The developer does not like your patch.
• The developer finds that you should change a few things.
• The developer finds the patch good and tells that he or she will work on it.
• The developer accepts your patch as it is.

The first case is when nobody has answered. That perhaps means that you have chosen the wrong mailing list. Perhaps you have not explained correctly what the patch fixes or you have given a title that is not precise enough. If this happens, the developer might have overlooked the patch. Perhaps the developer that should have answered has not any time currently. (That too happens unfortunately.) The best is to try to work a little more on the patch, make a better description and try again a second time, perhaps to another mailing list or to use KDE Bugs instead.

If the developer tells you that your patch conflicts with changes that he or she is currently doing, you could probably not do much against it. Maybe you can discuss with him how you can effectively work with him on this piece of code.

If your patch was not accepted, you could work further on it. Probably you should discuss the problem on the mailing list to know in which direction you should work further.

If a developer wants a few changes, then work on the code to make the changes according to the critic. If you need help because you do not understand how to do the needed change, then ask it on the mailing list.

If your patch was accepted, congratulations! :)