Get Involved
Download!
APR Docs
APR-util Docs
APR-iconv Docs
Guidelines
Miscellaneous
|
Creating Patches
|
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.
|
Code Style
|
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.
|
Patch Format
|
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.
|
Submitting Your Patch
|
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 dev@apr.apache.org, 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.
|
|