User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
Next revision Both sides next revision
cppdev:submitpatches [2010-01-06 15:44]
Carsten created
cppdev:submitpatches [2015-05-18 22:09]
127.0.0.1 external edit
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 large degree 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. 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. 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.+Remember that if you have any questions about the steps here, you can always post them at the [[http://forum.cafu.de|Cafu forum]] and we'll do our best to help you.
  
  
Line 13: Line 14:
  
 === Follow the rules === === Follow the rules ===
-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.+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.
  
 === Provide documentation === === Provide documentation ===
Line 26: Line 27:
 Always make your patches against the latest version of Cafu. 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]].+In most of the cases, you should make a patch against the head revision of the SVN trunk. You can learn how to checkout ​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.+If you cannot access the Subversion repository (for example when you are behind a firewall), make the patch against the latest source code release ​from the [[http://​www.cafu.de/​downloads|Downloads]] page.
  
 === Standard patch format === === Standard patch format ===
Line 36: Line 37:
  
 There are several ways to create patches: 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.+  * [[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 using ''​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''​.   * 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.   * 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.
Line 44: Line 45:
  
 === Omit auto-generated files === === Omit auto-generated files ===
-Don't include auto-generated files (log files, temporary scripts, etc.) in the patch. ​+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.+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 ​the unwanted ​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.+Do not combine multiple new features in a single patch: 
 +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.
  
-Another exampleif you adapted ​the build system ​to work on new, previously unsupported platform, we would gladly accept your patchJust send us single patchnot 10 patches, one for each modified file.+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 patchesThey are related to onelogically indivisible thingso they should be in one common patch.
  
  
Line 68: Line 71:
 === Let us know your name === === Let us know your name ===
 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. 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.
 +
 +
 +===== Copyright Considerations =====
 +
 +From a strictly legal point of view, when you submit a patch or another contribution,​ you are the /​*exclusive*/​ copyright holder of your contribution,​ and CFS is the /​*exclusive*/​ copyright holder of Cafu.
 +If we now integrated your contribution into Cafu, the result would be a mixed edition that is partly copyrighted by CFS, and partly copyrighted by you. Over time, the mix would grow more and more intermingled,​ to the extent to which many contributions from many different authors were merged in. The end result would quickly become an unmanageable and chaotic mess.
 +
 +As a consequence,​ not being the exclusive copyright owner any more, we would no longer be able to make crucial decisions on behalf Cafu as a whole:
 +  * We would not be legally able to distribute the "​new"​ edition of Cafu under the GPL(!).
 +  * We would not have the continuing ability to sell commercial licenses.
 +  * We would not reliably be able to enforce the GPL in court against violators.
 +These actions would instead require the consent of all copyright holders of the new, "​mixed"​ Cafu edition, and all future editions that are ever to be released --- a practical impossibility.
 +
 +/* ((These actions require the exclusive copyright of Cafu. In other words: Nobody except CFS can ever legally distribute Cafu under a license other than GPL -- an important feature that we need to fight possible GPL violations and thus the spirit of free software.)) */
 +
 +<​HTML><​p style="​border:​ 1px solid red; padding: 0.5em;">​Therefore,​ when you contribute source code to Cafu, we ask you to assign the copyright of your contribution to <acronym title="​Carsten Fuchs Software">​CFS</​acronym>,​ or &ndash; if that is not possible under your national law &ndash; to disclaim all interest in your copyright and grant <acronym title="​Carsten Fuchs Software">​CFS</​acronym>​ the right to use your contribution in the Cafu Engine as outlined above.</​p></​HTML>​
 +
 +Here is the single most pressing question that we assume occurs to most people now:
 +|   // Wait a moment! You plan to earn money from an edition of Cafu that my (substantial) contribution has been integrated in?? //   |
 +
 +When a patch is submitted at the issue tracker, it is integrated into the official Cafu source code, from where it is available under the GPL and the commercial licenses. Please consider why we still think that this is a win for you as well:
 +
 +  * We believe in the principle of reciprocity,​ "Quid Pro Quo", which literally translated means "​something for something"​. When we made Cafu available as free software, free to use for everyone in the world for any purpose, we gave a work to the community that has cost us a combined effort of several dozen man years to create. All that work and resources had to be paid for, and it has been possible only because of huge financial and personal efforts by the Cafu team. We didn't get rich, but earn enough to continue, and we love our work. Please ask yourself not only what you give, but also what you got.
 +
 +  * The authorship and all credits remain with you. Your contributions will clearly carry your name and everything gets properly documented in our changelog (unless you tell us otherwise).
 +
 +  * Once your code has been integrated into Cafu, we assume maintenance for it as for everything else. That means that we make sure that the code will still work after future changes, in future releases, on future platforms, etc.
 +
 +  * Any money we earn from selling commercial licenses is spent on the development and continued enhancement of Cafu. The code, insight and knowledge that we obtain from additional budget or manpower is directly given back to the community (most prominently in the form of commits to the [[cppdev:​gettingstarted|Cafu source code repository]]).
 +
 +  * We understand our responsibility from publishing Cafu as free software being greater than running some web and version control servers. We try to make good software for everyone, we provide support (often also for free), and if the GPL is violated (and thus //your// rights are as well), we take action. These concerns normally apply to //every// free software project, but not every maintainer cares enough about the legal details or liabilities (or lives in a legal system where they do not play a role) to bother you with this. We do.
 +
 +  * Not an argument, but a complementary piece of information:​ The instrument of copyright assignment is used by others in order to address similar concerns as well. For example, the Free Software Foundation (FSF) asks authors to assign the copyright of their contributions to the FSF too, /* because only then can they properly enforce the GPL in court against violators, */ see [[http://​www.gnu.org/​licenses/​gpl-faq.html#​AssignCopyright|the related GPL FAQ]] and [[http://​www.gnu.org/​licenses/​why-assign.html|Professor Moglens statement]] for details.
 +
 +In summary, the assignment of copyright is not only legally necessary;
 +we also believe that it is fair, preserves your rights, and generally helps free software.
 +
 +If you disagree, please [[info@cafu.de|let us know]] what bothers you.
 +We'll do our best to answer your questions and fix whatever is wrong.
 +But please understand that if you disagree, you cannot use the issue tracker for submitting your patch, and that we thus cannot accept and integrate your contribution into the Cafu Engine.
  
  
Line 75: Line 118:
   * Remember to add any relevant information or docs.   * Remember to add any relevant information or docs.
  
-** Thank you for reading this document ​-- we're looking forward to your patches! **+** Thank you very much for reading this document. If you have any questions, please [[info@cafu.de|let us know]]. We're looking forward to your patches! **  :-D
  
cppdev/submitpatches.txt · Last modified: 2017-02-05 13:37 by Carsten