diff options
Diffstat (limited to 'libs/libcurl/docs/CONTRIBUTE')
| -rw-r--r-- | libs/libcurl/docs/CONTRIBUTE | 310 |
1 files changed, 0 insertions, 310 deletions
diff --git a/libs/libcurl/docs/CONTRIBUTE b/libs/libcurl/docs/CONTRIBUTE deleted file mode 100644 index 75e7ebbb93..0000000000 --- a/libs/libcurl/docs/CONTRIBUTE +++ /dev/null @@ -1,310 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - - 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 - 3.6 Please don't send pull requests - -============================================================================== - -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 curl-library 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 - - Use the same indenting levels and bracing method as all the other code - already does. It makes the source code 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. - - Also, separate patches enable bisecting much better when we track problems in - the future. - -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! - - If you don't have test cases or perhaps you have done something that is very - hard to write tests for, do explain exactly how you have otherwise tested and - verified your changes. - -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 repository: - - 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 'git 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 - - Submit your patch to the curl-library mailing list. - - Make the patch against as recent sources as possible. - - 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. - - 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. - - If you've followed the above 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 - -3.6 Please don't send pull requests - - With git (and especially github) it is easy and tempting to send a pull - request to one or more people in the curl project to have changes merged this - way instead of mailing patches to the curl-library mailing list. - - We don't like that. We want them mailed for these reasons: - - - Peer review. Anyone and everyone on the list can review, comment and - improve on the patch. Pull requests limit this ability. - - - Anyone can merge the patch into their own trees for testing and those who - have push rights can push it to the main repo. It doesn't have to be anyone - the patch author knows beforehand. - - - Commit messages can be tweaked and changed if merged locally instead of - using github. Merges directly on github requires the changes to be perfect - already, which they seldom are. - - - Merges on github prevents rebases and even enforces --no-ff which is a git - style we don't otherwise use in the project - - However: once patches have been reviewed and deemed fine on list they are - perfectly OK to be pulled from a published git tree. |