diff options
Diffstat (limited to 'docs/CONTRIBUTE')
| -rw-r--r-- | docs/CONTRIBUTE | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/docs/CONTRIBUTE b/docs/CONTRIBUTE new file mode 100644 index 000000000..db03c42a1 --- /dev/null +++ b/docs/CONTRIBUTE @@ -0,0 +1,279 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + When Contributing Source Code + + This document is intended to offer guidelines that can be useful to keep in + mind when you decide to contribute to the project. This concerns new features + as well as corrections to existing flaws or bugs. + + 1. Learning cURL + 1.1 Join the Community + 1.2 License + 1.3 What To Read + + 2. cURL Coding Standards + 2.1 Naming + 2.2 Indenting + 2.3 Commenting + 2.4 Line Lengths + 2.5 General Style + 2.6 Non-clobbering All Over + 2.7 Platform Dependent Code + 2.8 Write Separate Patches + 2.9 Patch Against Recent Sources + 2.10 Document + 2.11 Test Cases + + 3. Pushing Out Your Changes + 3.1 Write Access to git Repository + 3.2 How To Make a Patch with git + 3.3 How To Make a Patch without git + 3.4 How to get your changes into the main sources + 3.5 Write good commit messages + +============================================================================== + +1. Learning cURL + +1.1 Join the Community + + Skip over to http://curl.haxx.se/mail/ and join the appropriate mailing + list(s). Read up on details before you post questions. Read this file before + you start sending patches! We prefer patches and discussions being held on + the mailing list(s), not sent to individuals. + + Before posting to one of the curl mailing lists, please read up on the mailing + list etiquette: http://curl.haxx.se/mail/etiquette.html + + We also hang out on IRC in #curl on irc.freenode.net + +1.2. License + + When contributing with code, you agree to put your changes and new code under + the same license curl and libcurl is already using unless stated and agreed + otherwise. + + If you add a larger piece of code, you can opt to make that file or set of + files to use a different license as long as they don't enforce any changes to + the rest of the package and they make sense. Such "separate parts" can not be + GPL licensed (as we don't want copyleft to affect users of libcurl) but they + must use "GPL compatible" licenses (as we want to allow users to use libcurl + properly in GPL licensed environments). + + When changing existing source code, you do not alter the copyright of the + original file(s). The copyright will still be owned by the original + creator(s) or those who have been assigned copyright by the original + author(s). + + By submitting a patch to the curl project, you are assumed to have the right + to the code and to be allowed by your employer or whatever to hand over that + patch/code to us. We will credit you for your changes as far as possible, to + give credit but also to keep a trace back to who made what changes. Please + always provide us with your full real name when contributing! + +1.3 What To Read + + Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS, the + most recent CHANGES. Just lurking on the libcurl mailing list is gonna give + you a lot of insights on what's going on right now. Asking there is a good + idea too. + +2. cURL Coding Standards + +2.1 Naming + + Try using a non-confusing naming scheme for your new functions and variable + names. It doesn't necessarily have to mean that you should use the same as in + other places of the code, just that the names should be logical, + understandable and be named according to what they're used for. File-local + functions should be made static. We like lower case names. + + See the INTERNALS document on how we name non-exported library-global + symbols. + +2.2 Indenting + + Please try using the same indenting levels and bracing method as all the + other code already does. It makes the source code a lot easier to follow if + all of it is written using the same style. We don't ask you to like it, we + just ask you to follow the tradition! ;-) This mainly means: 2-level indents, + using spaces only (no tabs) and having the opening brace ({) on the same line + as the if() or while(). + + Also note that we use if() and while() with no space before the parenthesis. + +2.3 Commenting + + Comment your source code extensively using C comments (/* comment */), DO NOT + use C++ comments (// this style). Commented code is quality code and enables + future modifications much more. Uncommented code risk having to be completely + replaced when someone wants to extend things, since other persons' source + code can get quite hard to read. + +2.4 Line Lengths + + We write source lines shorter than 80 columns. + +2.5 General Style + + Keep your functions small. If they're small you avoid a lot of mistakes and + you don't accidentally mix up variables etc. + +2.6 Non-clobbering All Over + + When you write new functionality or fix bugs, it is important that you don't + fiddle all over the source files and functions. Remember that it is likely + that other people have done changes in the same source files as you have and + possibly even in the same functions. If you bring completely new + functionality, try writing it in a new source file. If you fix bugs, try to + fix one bug at a time and send them as separate patches. + +2.7 Platform Dependent Code + + Use #ifdef HAVE_FEATURE to do conditional code. We avoid checking for + particular operating systems or hardware in the #ifdef lines. The + HAVE_FEATURE shall be generated by the configure script for unix-like systems + and they are hard-coded in the config-[system].h files for the others. + +2.8 Write Separate Patches + + It is annoying when you get a huge patch from someone that is said to fix 511 + odd problems, but discussions and opinions don't agree with 510 of them - or + 509 of them were already fixed in a different way. Then the patcher needs to + extract the single interesting patch from somewhere within the huge pile of + source, and that gives a lot of extra work. Preferably, all fixes that + correct different problems should be in their own patch with an attached + description exactly what they correct so that all patches can be selectively + applied by the maintainer or other interested parties. + +2.9 Patch Against Recent Sources + + Please try to get the latest available sources to make your patches + against. It makes the life of the developers so much easier. The very best is + if you get the most up-to-date sources from the git repository, but the + latest release archive is quite OK as well! + +2.10 Document + + Writing docs is dead boring and one of the big problems with many open source + projects. Someone's gotta do it. It makes it a lot easier if you submit a + small description of your fix or your new features with every contribution so + that it can be swiftly added to the package documentation. + + The documentation is always made in man pages (nroff formatted) or plain + ASCII files. All HTML files on the web site and in the release archives are + generated from the nroff/ASCII versions. + +2.11 Test Cases + + Since the introduction of the test suite, we can quickly verify that the main + features are working as they're supposed to. To maintain this situation and + improve it, all new features and functions that are added need to be tested + in the test suite. Every feature that is added should get at least one valid + test case that verifies that it works as documented. If every submitter also + posts a few test cases, it won't end up as a heavy burden on a single person! + +3. Pushing Out Your Changes + +3.1 Write Access to git Repository + + If you are a frequent contributor, or have another good reason, you can of + course get write access to the git repository and then you'll be able to push + your changes straight into the git repo instead of sending changes by mail as + patches. Just ask if this is what you'd want. You will be required to have + posted a few quality patches first, before you can be granted push access. + +3.2 How To Make a Patch with git + + You need to first checkout the respository: + + git clone git://github.com/bagder/curl.git + + You then proceed and edit all the files you like and you commit them to your + local repository: + + git commit [file] + + As usual, group your commits so that you commit all changes that at once that + constitutes a logical change. See also section "3.5 Write good commit + messages". + + Once you have done all your commits and you're happy with what you see, you + can make patches out of your changes that are suitable for mailing: + + git format-patch remotes/origin/master + + This creates files in your local directory named NNNN-[name].patch for each + commit. + + Now send those patches off to the curl-library list. You can of course opt to + do that with the 'get send-email' command. + +3.3 How To Make a Patch without git + + Keep a copy of the unmodified curl sources. Make your changes in a separate + source tree. When you think you have something that you want to offer the + curl community, use GNU diff to generate patches. + + If you have modified a single file, try something like: + + diff -u unmodified-file.c my-changed-one.c > my-fixes.diff + + If you have modified several files, possibly in different directories, you + can use diff recursively: + + diff -ur curl-original-dir curl-modified-sources-dir > my-fixes.diff + + The GNU diff and GNU patch tools exist for virtually all platforms, including + all kinds of Unixes and Windows: + + For unix-like operating systems: + + http://www.gnu.org/software/patch/patch.html + http://www.gnu.org/directory/diffutils.html + + For Windows: + + http://gnuwin32.sourceforge.net/packages/patch.htm + http://gnuwin32.sourceforge.net/packages/diffutils.htm + +3.4 How to get your changes into the main sources + + 1. Submit your patch to the curl-library mailing list + + 2. Make the patch against as recent sources as possible. + + 3. Make sure your patch adheres to the source indent and coding style of + already existing source code. Failing to do so just adds more work for me. + + 4. Respond to replies on the list about the patch and answer questions and/or + fix nits/flaws. This is very important. I will take lack of replies as a + sign that you're not very anxious to get your patch accepted and I tend to + simply drop such patches from my TODO list. + + 5. If you've followed the above mentioned paragraphs and your patch still + hasn't been incorporated after some weeks, consider resubmitting it to the + list. + +3.5 Write good commit messages + + A short guide to how to do fine commit messages in the curl project. + + ---- start ---- + [area]: [short line describing the main effect] + + [separate the above single line from the rest with an empty line] + + [full description, no wider than 72 columns that describe as much as + possible as to why this change is made, and possibly what things + it fixes and everything else that is related] + ---- stop ---- + + Don't forget to use commit --author="" if you commit someone else's work, + and make sure that you have your own user and email setup correctly in git + before you commit + |