Difference between revisions of "Contribute/Send Patches"

Jump to: navigation, search
(Change Reviewboard to Phabricator)
 
(9 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
== Notation ==
 
== Notation ==
  
The word ''developer'' is used here for someone having a KDE SVN account.
+
The word ''developer'' is used here for someone having a [https://identity.kde.org/ KDE Identity account].
  
 
== Preliminaries ==
 
== Preliminaries ==
Line 17: Line 17:
 
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.")
 
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.
+
== Phabricator ==
 +
'''Most KDE projects are switching to [[Development/Phabricator | 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.
  
== Creating a Simple File Patch ==
+
The older way of submitting patches is [[Development/Review_Board|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.
  
The most simple patch is created between the modified file (here called {{path|source.cpp}}) and the non-modified version of the file (here called {{path|source.cpp.orig}}.)
+
== Creating patches with git ==
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.
+
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:
diff -u -p source.cpp.orig source.cpp > ~/patch.diff
+
  
{{path|~/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.)
+
git diff > ~/patch.diff
  
== The More Common Case ==
+
There are useful variants too (shown here without redirection):
 +
* For just one file: '''git diff source.cpp'''
 +
* For the current directory only: '''git diff '''.
  
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.
+
'''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.)
  
The program svn, which is used on the command line interact with the SVN server, has a diff function too: '''svn diff'''.
+
'''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.
  
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.
+
=== New Files ===
  
  svn diff > ~/patch.diff
+
First, you need to make Git aware of files you have added.
 +
  git add path/to/new/file /path/to/another/new/file
  
There are useful variants too (shown here without redirection)
+
Then, "git status" will show you that the file has indeed been added to the repository.
* 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.)
+
== Creating patches without git ==
  
'''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.)
+
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.
  
By default, svn diff does not have a feature like the <tt>-p</tt> parameter of diff. But svn allows that an external diff program is called, so you can call diff:
+
The most simple patch is created between the modified file (here called {{path|source.cpp}}) and the non-modified version of the file (here called {{path|source.cpp.orig}}.)
  svn diff --diff-cmd diff --extensions "-u -p"
+
  diff -u -p source.cpp.orig source.cpp
  
== Non-Text Files ==
+
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 &gt; ~/patch.diff
  
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.
+
{{path|~/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.)
 
+
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 [http://bugs.kde.org 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 [[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.
+
 
+
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 [http://bugs.kde.org 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 [[Development/Further_Information#IRC_Channels|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 [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.)
+
 
+
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 [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: ''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.
+
=== Non-Text Files ===
  
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.
+
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.
  
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.
+
Therefore, unfortunately, there is little choice but to attach binary files separately from the patch.
  
Now check the email again to see if you have not forgotten anything (especially to attach the patch) and you can send the email.
+
== Patches for KDE Bugs ==
  
=== Reviewboard ===
+
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.
  
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.
+
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? ===
+
== 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 [http://lists.kde.org the mailing list archives]] for such a message.)
 
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 [http://lists.kde.org the mailing list archives]] for such a message.)
Line 139: Line 73:
 
The reaction is normally one of the following:
 
The reaction is normally one of the following:
 
* No developer answers. (That is unfortunately happening from time to time.)
 
* 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 want your patch, as he or she is working on the same code.
 
* The developer does not like your patch.
 
* The developer does not like your patch.
 
* The developer finds that you should change a few things.
 
* 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 finds the patch good and tells that he or she will work on it.
 
* 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 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.
 
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 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 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.

Latest revision as of 01:15, 17 August 2015

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

Contents

[edit] Notation

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

[edit] 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.

[edit] 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.")

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.)

[edit] 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.

[edit] 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.

[edit] 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! :)


This page was last modified on 17 August 2015, at 01:15. This page has been accessed 33,331 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal