How To Create and Submit a Patch
Introduction
A patch is exactly what the word says: a small piece of code used to repair a breach. It is normally a plain text file containing only the differences between the current version of the code and the fixed version.
- Many people have been submitting patches to the mailing lists and this is a small problem, the patch might be big and sending the patch via mail might not be a very good idea.
Generating a Patch
Against Current Subversion
- The preferred way of creating a patch is to create it against current Subversion. The ensures that the patch works with the latest edition of the source code and makes it easier for the developers to apply the patch.
To generate the patch you need to check out a copy of the source code from Subersion. More information on how to do this can be found in the SubersionHowto. After you have made the changes to the source code and made sure it works as expected, you can create the patch file using the command "svn diff > /path/to/patchfile.patch". To summarize the steps:
- Check out a copy of the source code from Subversion
- Apply your changes to the source
- Re-compile and make sure it works as expected
Generate the patch file using svn diff > /path/to/patchfile.patch
- Examine the resulting .patch file to make sure it contains only the intended changes
Submit the patch using http://bugs.cacert.org/, see below
Against the Latest Release
If you do not have access to Subversion you can generate the patch against the latest release.
- To generate the patch you will need two copies of the source code: one that is unmodified and one containing your changes to the source. Start by downloading the source code of the latest release, extract it and make a copy of the entire source directory. After you have made your changes to one of the source directories and made sure it compiles and works as expected, you can create the patch file using the command
diff -rup /path/to/unmodified/source /path/to/modified/source > /path/to/patchfile.patch.
To summarize the steps:
- Download the source code of the latest release
- Extract the source code
- Make a copy of the source code directory
- Apply your changes to the copy of the source code
- Make sure it works as expected
- Do a make clean to remove files generated during build
Generate the patch file using diff -rup /path/to/unmodified/source /path/to/modified/source > /path/to/patchfile.patch
- Examine the resulting .patch file to make sure it contains only the intended changes
Submit the patch using http://bugs.cacert.org/ , see below
Usual patch problems
If you never made a patch before, that was submitted to a project, you will likely make the following mistakes:
- Editing Unix sourcefiles on Windows, and generating a diff afterwards.
The problem is that Windows an Unix has different line endings, and therefore diff thinks that the whole file changed, creating an unusable patch, that contains the whole file instead of a couple of lines that were changed.
- Patch in the wrong direction.
When you mix original and modified tree, when doing the diff -ru, then you will get a patch, that undoes your changes from an already patched system, instead of applying your changes to an unpatched system. You can detect a correct patch yourself: If you have added some code, you should see more "+" at the begining of the lines than "-" in the patch file. If you see more "-" than "+", then you likely made the patch in the wrong direction.
Using Bugtracker
Closing a bug patch
The best way to submit a patch to the CAcert development is to send it to http://bugs.cacert.org/ and inform the rest of the team what the patch is doing:
- Is it closing bugs?
- Is it a enhancement?
- What are the changes in the code?
- Are there any know problems with the patch?
If you have a patch that is closing bugs then you can attach the patch to the bug/bugs explaining what the patch is doing. You can also inform the cacert-dev mailing list ( http://lists.cacert.org/ )about the closed bug but don't attach the patch to the mail sent to the list, instead put the bug links in the mail where the attached patch is located. Test the patch locally on your own machine and look if it closes the bug there. Find the bug it is closing in the Open bugs list. Attach the patch to the bug report. Explain what the patch is doing and if there might be any problems with the patch. If you want to send a mail to the cacert-dev list and explain it there also. Remember to have the bug number or even better the link to the bug in the mail. Don't attach the patch to the mail.
- Now you just have to wait for the developers and maintainers to look at the patch and see if this is really closing the bug and if it might open new bugs. With a bit of luck it will be implemented soon.
How about enhancements?
Start a new bug report, mark it as enhancement and put the patch in that report on http://bugs.cacert.org/. This will give developers a good explanation of why you did the patch and how the patch changes CAcert source or adds new things to it. The only thing you need to add to the report is that it is an enhancement and explain the patch a little bit. A simple way to this is to:
- Go to Submit a new bug report.
- Fire up a new report and select enhancement instead of the others used by normal bug reporting.
- Attach the patch and explain what you wanted to get going with the help of this patch.
- Remember to explain the purpose of the patch and who might want to use this enhancement.
- Thats it! You have done a patch reporting enhancement all that is left is for the developers to look at the report and the patch. They might get even better ideas of how to implement this with the help of the patch you sent.
- Please try to use the same coding style.
- explain what the patch is doing to CAcert.
- report the bugs that the patch is closing.
- always test the patch before submitting it.
- write what version it is tested on.
THANKS FOR YOUR HELP!