User Tools
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
cppdev:submitpatches [2010-01-06 15:44] Carsten created |
cppdev:submitpatches [2017-02-05 13:37] (current) Carsten Remove more obsolete text |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== How to Submit Patches ====== | ====== How to Submit Patches ====== | ||
| - | User contributions and especially patches are very important for Cafu. | + | Cafu is to a community project and we need and very much appreciate your help. |
| - | Patches help us to add new features, improve code quality and fix bugs, so we are happy if you contribute them (how could we dislike your help, after all?). :-) | + | Your contributions and especially patches are very important for Cafu. |
| - | + | Patches help us to add new features, improve code quality and fix bugs, so we are happy and grateful if you contribute them. :-D | |
| - | However, we have all sort of problems with applying non-standard patches. | + | |
| - | To make life easier for both you and us, please follow the few simple rules below when submitting patches. | + | |
| - | + | ||
| - | Remember that if you have any questions about the steps here, you can always post them to the [[http://www.cafu.de/forum/|Cafu forum]] and we'll do our best to help you. | + | |
| ===== Changing Cafu ===== | ===== Changing Cafu ===== | ||
| - | === Follow the rules === | + | Please read the [[cppdev:codingconventions]] and try to conform to them. In particular, please respect the indentation rules (4 spaces, no TABs) -- patches are really difficult to read otherwise. |
| - | Read the [[cppdev:codingconventions]] and try to conform to them. In particular, please respect the indentation rules (4 spaces, no TABs) -- patches are really difficult to read otherwise. | + | |
| === Provide documentation === | === Provide documentation === | ||
| Line 19: | Line 14: | ||
| Therefore, please provide any required documentation such as source code comments (preferably in familiar and simple [[http://www.doxygen.org|Doxygen]] format), high-level overviews, diagrams, etc. Without documentation, another developer would have to write it, and the patch cannot be applied until he has time to do it. | Therefore, please provide any required documentation such as source code comments (preferably in familiar and simple [[http://www.doxygen.org|Doxygen]] format), high-level overviews, diagrams, etc. Without documentation, another developer would have to write it, and the patch cannot be applied until he has time to do it. | ||
| - | |||
| - | |||
| - | ===== Mechanics of Patch Submission ===== | ||
| - | |||
| - | === Use the latest version === | ||
| - | Always make your patches against the latest version of Cafu. | ||
| - | |||
| - | In most of the cases, you should make a patch against the head revision of the SVN trunk. You can learn how to download the source code from the Subversion repository [[cppdev:gettingstarted|here]]. | ||
| - | |||
| - | If you cannot access the Subversion repository (for example when you are behind a firewall), make the patch against the latest source code release at the [[http://www.cafu.de/downloads|Downloads]] page. | ||
| - | |||
| - | === Standard patch format === | ||
| - | A patch is a single file that contains the differences in all files that you modified. Patch files are small, easy to read and understand and can be applied with a single command, even if the affected files have been changed since the moment when the patch was created. | ||
| - | |||
| - | Therefore, do **not** send us ZIP archives, whole files, code snippets or other arbitrary text that we'd spend hours trying to understand. | ||
| - | |||
| - | There are several ways to create patches: | ||
| - | * [[http://tortoisesvn.net/|{{ http://tortoisesvn.tigris.org/tortoisesvn_logo_hor468x64.PNG}}]] Use [[http://tortoisesvn.net/|TortoiseSVN]] or a similar GUI client for Subversion. TortoiseSVN integrates into the Windows explorer and can create patches comfortably from the right-click context menu. It also allows you to select the individual files that should or shouldn't be included in the patch. Thus we recommend that you use TortoiseSVN, especially if you don't feel comfortable with ''svn diff'' at the command-line. | ||
| - | * Also straightforward and easy is the use of ''svn diff'' at the command-line: <code>svn diff > mypatch.patch</code> Similar to TortoiseSVN, if your patch adds or removes files, you should run ''svn add'' or ''svn remove'' before ''svn diff''. | ||
| - | * If you don't use Subversion at all, you can use the ''diff'' program which is a standard part of most Unix systems and is available as part of the Cygwin package or elsewhere for Windows: <code>diff -uNr Cafu-src-orig Cafu-src-mine > mypatch.patch</code> Use the ''-u'' option for unified diff output and ''-N'' for the new files to be included in the patch. | ||
| - | |||
| - | === Standard patch file extensions === | ||
| - | Use standard extension ''.diff'' or ''.patch'' for the patch file. | ||
| - | |||
| - | === Omit auto-generated files === | ||
| - | Don't include auto-generated files (log files, temporary scripts, etc.) in the patch. | ||
| - | |||
| - | The simplest way to handle this is to use TortoiseSVN, which allows you to select which files should and which files shouldn't be included in the patch. Alternatively, it is also easy to edit the patch to remove appropriate chunks. | ||
| === Make atomic patches === | === Make atomic patches === | ||
| - | Do not split single code change into multiple patches. A patch should be self-contained -- //one patch for one thing//. | + | A patch should be self-contained -- //one patch for one thing//. |
| - | + | ||
| - | A patch that adds bitmaps to menu items and fixes a bug in the network code is a bad patch. It should be splitted into two patches. On the other hand, two patches, one of them being "implementation of new member-functions", the other "changes in class description to accommodate new members" are two bad patches. They are related to one, logically indivisible, thing, so they should be part of one patch. | + | |
| - | + | ||
| - | Another example: if you adapted the build system to work on new, previously unsupported platform, we would gladly accept your patch. Just send us single patch, not 10 patches, one for each modified file. | + | |
| - | + | ||
| - | + | ||
| - | ===== Submitting the Patch ===== | + | |
| - | + | ||
| - | === Use Trac === | + | |
| - | Please do **not** send the patches to the forum, mailing list, or to any developer's personal email address. Instead, use the [[http://trac.cafu.de|issue tracker]]. Then you will be notified about the progress the patch makes, e.g. when the patch is accepted or if there is a problem with applying the patch. | + | |
| - | + | ||
| - | === Describe your changes === | + | |
| - | Please fill in the ticket form as explained at [[cppdev:SubmitTickets]]. | + | |
| - | + | ||
| - | Remember that it is often not easy to understand the purpose of your patch just from its source code. If you provide detailed description of the patch, we will be able to apply it much faster -- and we will love you for submitting such nice patches! :-D | + | |
| - | === Let us know your name === | + | Do not combine multiple new features in a single patch: |
| - | We'd also like to give you credit for your patch (unless it's something really trivial as we avoid mentioning very small changes in our changelog) but we need to know your real name for this. Please tell us if we don't know you already e.g. from the forum. | + | A patch that adds bitmaps to menu items and fixes a bug in the network code is a bad patch. It should be splitted into two patches. |
| + | On the other hand, do not split a single code change into multiple patches: | ||
| + | Two patches, one of them being "implementation of new member-functions", the other "changes in class documentation to accommodate new members" are two bad patches. They are related to one, logically indivisible thing, so they should be in one common patch. | ||
| - | ===== Summary ===== | ||
| - | * Attach a unified diff against the SVN trunk to a ticket in the [[http://trac.cafu.de|issue tracker]]. | + | ===== Final Considerations ===== |
| - | * Remember to add any relevant information or docs. | + | |
| - | ** Thank you for reading this document -- we're looking forward to your patches! ** | + | - On Dive-In, we need "How to contribute" / "Fork me on Bitbucket". |
| + | - Why Your Project Doesn't Need a Contributor Licensing Agreement, http://ebb.org/bkuhn/blog/2014/06/09/do-not-need-cla.html | ||
| + | - https://kernel.org/doc/html/latest/process/submitting-patches.html | ||
cppdev/submitpatches.1262789096.txt.gz · Last modified: 2013-01-07 12:07 (external edit)