Imported Upstream version 7.21.3upstream/7.21.3

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
+