This tutorial is about how to send modifications of code by the way of patches.
The word developer is used here for someone having a ADempiere SVN account.
Say that you have modified some code in ADempiere and 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.")
Creating A Simple File Patch
Use the svn command line tool or the Eclipse subversion plugin to create a patch file.
- select the "Java" perspective
- select the "Navigator" window
- select the file you want to create a patch for
- mouse right-click and select "Team/Create Patch"
- choose where the patch file is to be stored
The procedures describe above works very well with text files, for example Java 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.
Therefore, unfortunately, there is little choice but to attach binary files separately from the patch.
In short: svn diff cannot take care of new file if you do not have a write access on the SVN. So the modified source file needs to be uploaded.
If your patch fixes a bug from ADempeire Bugs, then the easiest way is to attach it there. (See next section)
The main way of sharing a patch is to upload to the sourceforge ADempiere patch tracker.
Another possibility, however seldom used, is to post the patch on a public Web server (be it by HTTP or FTP) and to post the address to the Adempiere patch tracker, telling that the patch is waiting there.
Patches for ADempiere Bugs
In this section we assume that you have chosen to add your patch to an exisiting ADempeire bugs or that you create 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 Adempiere Bugs.
- online, by selecting the bug report and using the Web interface to add attachements.
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.
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. (This unfortunately happens 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 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 ADempiere Bugs instead.
If the developer tells that your patch conflicts with changes that he is currently doing, you could probably not do much against it. May be 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!