234 lines
9.2 KiB
Plaintext
234 lines
9.2 KiB
Plaintext
_ _ ____ _
|
|
___| | | | _ \| |
|
|
/ __| | | | |_) | |
|
|
| (__| |_| | _ <| |___
|
|
\___|\___/|_| \_\_____|
|
|
|
|
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 CVS Repository
|
|
3.2 How To Make a Patch
|
|
3.3 How to get your changes into the main sources
|
|
|
|
==============================================================================
|
|
|
|
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 try to keep 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 CVS 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 CVS Repository
|
|
|
|
If you are a frequent contributor, or have another good reason, you can of
|
|
course get write access to the CVS repository and then you'll be able to
|
|
check-in all your changes straight into the CVS tree instead of sending all
|
|
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 write access.
|
|
|
|
3.2 How To Make a Patch
|
|
|
|
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.3 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.
|