Difference between revisions of "Contribute/Send Patches"

Jump to: navigation, search
(New Files)
(24 intermediate revisions by 14 users not shown)
Line 52: Line 52:
 
== Non-Text Files ==
 
== Non-Text Files ==
  
The procedures describe above works 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 SVN can internally store binary differences, svn diff is not prepare to do anything similar yet, mainly because it currently only use the unified diff format too, which is not meant for binary data.
+
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 SVN can internally store binary differences, svn 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, unfortuntely, there is little choice but to attach binary files separately from the patch, of course attached in the same email.
+
Therefore, unfortunately, there is little choice but to attach binary files separately from the patch, of course attached in the same email.
  
 
== New Files ==
 
== New Files ==
Line 72: Line 72:
  
 
The main way of sharing a patch is to email to a mailing list. But be careful not to send big patches to a mailing list, a few 10KB is the limit.
 
The main way of sharing a patch is to email to a mailing list. But be careful not to send big patches to a mailing list, a few 10KB is the limit.
 +
 +
Some projects use [[Development/Review_Board|KDE's Review Board]] for patch submitting. If a project is using the Review Board, that is usually their preferred way of receiving patches.  See the [[Contribute/Send_Patches#Reviewboard|section below]] for details.
  
 
If you find that the patch is too big to send to a mailing list, the best is to create a bug report in [http://bugs.kde.org KDE Bugs] and to attach the patch there, after having created the bug report.
 
If you find that the patch is too big to send to a mailing list, the best is to create a bug report in [http://bugs.kde.org KDE Bugs] and to attach the patch there, after having created the bug report.
Line 79: Line 81:
 
Another variant is to ask on the mailing list which developer is ready to get a big patch. (Try to give its size and ask if you should send it compressed, for example by bzip2.)
 
Another variant is to ask on the mailing list which developer is ready to get a big patch. (Try to give its size and ask if you should send it compressed, for example by bzip2.)
  
A last variant, if you know exactly which developer will process the patch and that you know or that you suppose that he currently has time, is to send the patch to a developer directly. (But here too, be careful if your patch is big. Some KDE developers have still analog modems.)
+
A last variant, if you know exactly which developer will process the patch and that you know or that you suppose that he currently has time, is to send the patch to a developer directly. (But here too, be careful if your patch is big. Some KDE developers still have analog modems.)
  
 
=== Patches for KDE Bugs ===
 
=== Patches for KDE Bugs ===
  
In this section we assume that you have chosen to add your patch to an exisiting KDE bugs or that you create a bug report just for your patch.
+
In this section we assume that you have chosen to add your patch to an existing KDE bug or that you have created a bug report just for your patch.
  
 
Even if this tutorial is more meant to send patches to a mailing list, most of it can be applied to adding a patch to [http://bugs.kde.org KDE Bugs].
 
Even if this tutorial is more meant to send patches to a mailing list, most of it can be applied to adding a patch to [http://bugs.kde.org KDE Bugs].
  
 
You have two ways to do it:
 
You have two ways to do it:
* online, by selecting the bug report and using the web interface to add attachements.
+
* online, by selecting the bug report and using the web interface to add attachments.
 
* offline, by emailing to the bug report.
 
* offline, by emailing to the bug report.
  
Line 96: Line 98:
  
 
'''Note''': if you create a new bug report just for your patch, be careful that you cannot attach a patch directly when creating a new bug. However as soon as the new bug is created, you can then attach files, one-by-one, therefore also patches.
 
'''Note''': if you create a new bug report just for your patch, be careful that you cannot attach a patch directly when creating a new bug. However as soon as the new bug is created, you can then attach files, one-by-one, therefore also patches.
 +
 +
'''Warning''': sometimes your patch will be forgotten because the developers do not always closely monitor the bug database. In this case, try sending your patch by email as described below. If that also does not help, you can always talk to the developers on [[Development/Further_Information#IRC_Channels|IRC]]
  
 
=== Which Mailing List? ===
 
=== Which Mailing List? ===
  
Assuming that you have chosen to sent the patch to a mailing list, you might ask yourself: to which one?
+
Assuming that you have chosen to send the patch to a mailing list, you might ask yourself: to which one?
  
The best destination for patches is the [http://www.kde.org/mailinglists corresponding developer mailing list].
+
The best destination for patches is the [http://www.kde.org/mailinglists/ corresponding developer mailing list].
  
 
In case of doubt, you can send any patch for KDE to the [mailto:kde-devel@kde.org kde-devel mailing list]. (However with an increased risk that you would miss the right developer.)
 
In case of doubt, you can send any patch for KDE to the [mailto:kde-devel@kde.org kde-devel mailing list]. (However with an increased risk that you would miss the right developer.)
Line 117: Line 121:
 
Now you are ready to write the rest of the email. Please think of a title that matches your patch. (Think of having to find it again in [http://lists.kde.org the archives] in a few months or even years.) A good habit is to precede the title by <nowiki>[PATCH]</nowiki>. So for example a title could be <nowiki>[PATCH] Fix backup files</nowiki>.
 
Now you are ready to write the rest of the email. Please think of a title that matches your patch. (Think of having to find it again in [http://lists.kde.org the archives] in a few months or even years.) A good habit is to precede the title by <nowiki>[PATCH]</nowiki>. So for example a title could be <nowiki>[PATCH] Fix backup files</nowiki>.
  
As for the body of the email, please tell to which file or directory your patch applies. For example for a file:
+
As for the body of the email, please tell to which file or directory your patch applies. For example for a file: ''The attached patch applies to the file words/part/KWDocument.cpp'' or for a directory: ''The attached patch applies to the directory calligra/words''. This help the developers to have an overview of which code has been modified. Also tell for which branch it is meant, for example for trunk.
''The attached patch applies to the file koffice/kword/kwdoc.cpp'' or for a directory: ''The attached patch applies to the directory koffice/kword''. This help the developers to have an overview of which code has been modified. Also tell for which branch it is meant, for example for trunk.
+
  
 
Then tell what your patch does. If it fixes a bug, then please give the bug number too. If the bug was not registered in [http://bugs.kde.org KDE Bugs], then please describe instead the bug that is fixed. Similarly, if you know that the patch fixes a bug introduced from a precise SVN revision, please add the revision number.
 
Then tell what your patch does. If it fixes a bug, then please give the bug number too. If the bug was not registered in [http://bugs.kde.org KDE Bugs], then please describe instead the bug that is fixed. Similarly, if you know that the patch fixes a bug introduced from a precise SVN revision, please add the revision number.
  
Tell also what could be useful to the developers, for examples if you could not completely test the patch (and why), if you need help to finish fixing the code or if it is a quick&dirty solution that should be fixed better in long-term.
+
Tell also what could be useful to the developers, for example if you could not completely test the patch (and why), if you need help to finish fixing the code or if it is a quick&dirty solution that should be fixed better in long-term.
  
 
Now check the email again to see if you have not forgotten anything (especially to attach the patch) and you can send the email.
 
Now check the email again to see if you have not forgotten anything (especially to attach the patch) and you can send the email.
 +
 +
=== Reviewboard ===
 +
 +
One popular way of submitting patches is [[Development/Review_Board|KDE's Review Board]]. 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.
  
 
=== And Now? ===
 
=== And Now? ===
Line 138: Line 145:
 
* The developer accepts your patch as it is.
 
* 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 overseen 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 [http://bugs.kde.org KDE Bugs] instead.
+
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 [http://bugs.kde.org KDE Bugs] instead.
  
 
If the developer tells you that your patch conflicts with changes that he 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 the developer tells you that your patch conflicts with changes that he 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.
Line 146: Line 153:
 
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 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, congratulation! :)
+
If your patch was accepted, congratulations! :)

Revision as of 20:00, 12 July 2012

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

Contents

Notation

The word developer is used here for someone having a KDE SVN 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.")

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.

Creating a Simple File Patch

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.)

The More Common Case

But normally, you do not just change one file and you do not keep the original version around to be able to make the difference later. But here too, there is a solution.

The program svn, which is used on the command line interact with the SVN server, has a diff function too: svn 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, here too, you want to redirect the output.

svn diff > ~/patch.diff

There are useful variants too (shown here without redirection)

  • For just one file: svn diff source.cpp
  • For the current directory only: svn diff -N

Note: even if svn can make the difference of another directory (svn 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 applies it.)

Note: for simple diff, like those shown in the examples above, svn diff can be used offline, therefore without an active connection to the KDE SVN server. This is possible, as svn keeps a copy of the original files locally. (This feature is part of the design of SVN.)

By default, svn diff does not have a feature like the -p parameter of diff. But svn allows that an external diff program is called, so you can call diff:

svn diff --diff-cmd diff --extensions "-u -p"

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 SVN can internally store binary differences, svn 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, of course attached in the same email.

New Files

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

svn add path/to/new/file /path/to/another/new/file

Then run svn diff as before.

Note that if you do svn revert, for example, the files you created will NOT be deleted by svn - but svn will no longer care about them (so they won't show up when you do svn diff, for example). You will have to rm them manually.

(TODO: are there any other issues with adding new files if you don't have commit access?)

How To Share the Patch?

Now you are ready to share the patch. If your patch fixes a bug from KDE Bugs, then the easiest way is to attach it there, see next section.

The main way of sharing a patch is to email to a mailing list. But be careful not to send big patches to a mailing list, a few 10KB is the limit.

Some projects use KDE's Review Board for patch submitting. If a project is using the Review Board, that is usually their preferred way of receiving patches. See the section below for details.

If you find that the patch is too big to send to a mailing list, the best is to create a bug report in KDE Bugs and to attach the patch there, after having created the bug report.

Another possibility, however seldom used, is to post the patch on a public Web server (be it by HTTP or FTP) and to send an email to the mailing list, telling that the patch is waiting there.

Another variant is to ask on the mailing list which developer is ready to get a big patch. (Try to give its size and ask if you should send it compressed, for example by bzip2.)

A last variant, if you know exactly which developer will process the patch and that you know or that you suppose that he currently has time, is to send the patch to a developer directly. (But here too, be careful if your patch is big. Some KDE developers still have analog modems.)

Patches for KDE Bugs

In this section we assume that you have chosen to add your patch to an existing KDE bug or that you have created a bug report just for your patch.

Even if this tutorial is more meant to send patches to a mailing list, most of it can be applied to adding a patch to KDE Bugs.

You have two ways to do it:

  • online, by selecting the bug report and using the web interface to add attachments.
  • offline, by emailing to the bug report.

To send an email to a bug report, you can use an email address of the form 12345@bugs.kde.org where 12345 is the bug number. Please be sure to attach your patch and not to have it inlined in your text. (If it is inlined, it would be corrupted by KDE Bugs, as HTML does not respect spaces.)

Note: if you send an email to KDE Bugs, be careful to use as sender the same email address as your login email address in KDE Bugs. Otherwise KDE Bugs will reject your email.

Note: if you create a new bug report just for your patch, be careful that you cannot attach a patch directly when creating a new bug. However as soon as the new bug is created, you can then attach files, one-by-one, therefore also patches.

Warning: sometimes your patch will be forgotten because the developers do not always closely monitor the bug database. In this case, try sending your patch by email as described below. If that also does not help, you can always talk to the developers on IRC

Which Mailing List?

Assuming that you have chosen to send the patch to a mailing list, you might ask yourself: to which one?

The best destination for patches is the corresponding developer mailing list.

In case of doubt, you can send any patch for KDE to the kde-devel mailing list. (However with an increased risk that you would miss the right developer.)

Of course, if you know exactly which developer will process the patch and that you know or that you suppose that he currently has time, then you can send the patch to him directly.

Preparing The Email

Now you have a patch redirected into a file (for this example called patch.diff), you are ready to send it by email. But the first question: where?

Now that you have entered an email address, a good practice is to attach the patch to your file before writing anything else in the email. So you will not forget to attach it.

A little note here: yes, in KDE (unlike for the Linux Kernel for example), we prefer to have the patches sent as attachments.

Now you are ready to write the rest of the email. Please think of a title that matches your patch. (Think of having to find it again in the archives in a few months or even years.) A good habit is to precede the title by [PATCH]. So for example a title could be [PATCH] Fix backup files.

As for the body of the email, please tell to which file or directory your patch applies. For example for a file: The attached patch applies to the file words/part/KWDocument.cpp or for a directory: The attached patch applies to the directory calligra/words. This help the developers to have an overview of which code has been modified. Also tell for which branch it is meant, for example for trunk.

Then tell what your patch does. If it fixes a bug, then please give the bug number too. If the bug was not registered in KDE Bugs, then please describe instead the bug that is fixed. Similarly, if you know that the patch fixes a bug introduced from a precise SVN revision, please add the revision number.

Tell also what could be useful to the developers, for example if you could not completely test the patch (and why), if you need help to finish fixing the code or if it is a quick&dirty solution that should be fixed better in long-term.

Now check the email again to see if you have not forgotten anything (especially to attach the patch) and you can send the email.

Reviewboard

One popular way of submitting patches is KDE's Review Board. 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.

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 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 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 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! :)


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal