Like most Open Source projects, APR thrives on contributions from people who use it in their own projects. We want to make it as easy as possible for people to contribute code. However, we do have some expectations of code that is contributed. This is to help us review code as quickly as possible. If code is contributed that doesn't follow these guidelines, it might still be reviewed, but it will take longer and attract the attention of fewer developers. When you contribute, please remember that anyone evaluating your suggestion is a voulenteer contributor, just like yourself.

Currently APR is using the same code format as Apache. The Apache style-guide was debated for a long time before it the Apache Group settled on it, and because APR grew out of Apache code, it made sense to continue the same style. It is unlikely that this style will change at any time. The style-guide can currently be found on the Apache httpd dev site, here.

We also have very high expectations for code quality; and to us this means the avoidance of excessive static buffers, using the memory pool mechanism (which ensures proper cleanup), and otherwise writing thread-safe code. We also expect one or two levels of optimizations to be applied, too - is a bitmask faster for this? Is a strchr() faster than an index()? Etc. Of course it'd be nice if we had a real document describing this all, but we don't yet.

One notable standard that has been adopted within APR functions (and is partly due to APR's httpd lineage) is that the input values do not need to be checked for correctness. It is the responsibility of the calling program that uses APR to ensure that the input parameters are what APR expects. If the input parameters are invalid (NULL, for example), APR functions are expected to produce a segfault when it attempts to reference these variables. This increases the stability of consumer code, by forcing developers to fix code which might otherwise silently ignores fatal error conditions.

We request that patches be submitted in unified diff format:

diff -u file-old.c file.c

or if working with an svn checkout:

svn diff file.c

where file.c is the file affected. (Older versions of diff may require -u3 to display lines of context, but the current version of GNU diff has deprecated the trailing number for -u and presumes three lines, use -U# syntax if you wish to provide more lines of context.)

You can obtain the most sophisticated diff utility from the GNU diffutils project:

https://www.gnu.org/software/diffutils/diffutils.html

and Windows users can obtain a native port of diff and other useful utilites from:

http://unxutils.sourceforge.net/

If you cannot produce a unified diff, then at least please submit a context diff:

diff -C3 file-old.c file.c

We should be able to feed the patch directly into the "patch" program and have it update the file or set of files. The -u or -C3 is critical; the existing code changes regularly, so having context is crucial to understanding your patch and knowing where it all really goes. Patches without filenames, line numbers and surrounding context become impossible to consider as time goes on.

The best place to submit your patch is an attachment to a bug report:

https://issues.apache.org/bugzilla/

Be certain to research your patch, to ensure that it isn't already in an existing bug report, and that similiar code hasn't already been committed to the working development trunk:

https://svn.apache.org/repos/asf/apr/apr/trunk

https://svn.apache.org/repos/asf/apr/apr-util/trunk

https://svn.apache.org/repos/asf/apr/apr-iconv/trunk

Ensure your patch is attached as a text/ type file, and try retrieving it yourself after you add it, to ensure that others can, too. Do not submit links to other locations for your patch (or anyone else's patch!), as they will only be considered when submitted directly to the ASF by the original author.

If you are a subscriber to [email protected], you can also post your patch there, with the string "[PATCH]" prefixing your subject line, so everyone knows it's a patch. However, it's not guaranteed that your Patch will find an advocate within the developers' group; if we're too busy working on something else or everyone's on vacation, it could get lost in the noise. Feel free to resubmit your patch in a week or so if you have not yet received any feedback from the developers' group. Keep PPP (Patient, Polite, Persistent) in mind. Bring up your case again and again from time to time but don't try to be too much of a Pest. And stay polite. There is never bad will by the committers why your patch is being ignored. Most of the time it is simply lack of resources as they concentrate their resources on what looks more important from their point of view. So try to convince them that your stuff is important as well.

Also, there are often times when the core developers are in "feature freeze", when they are trying to iron out the remaining bugs in the code in preparation for a release.