This document describes how to contribute code to PoDoFo.

     2010 Dominik Seichter <domseichter@web.de>

0. Code quality
===============

Before you submit or commit code to PoDoFo (assuming you made a modification),
you should make sure that your code adheres to the codingstyle guidelines (see
CODINGSTYLE.txt). Note that the codingstyle guidelines also include
documenting every newly introduced method (Doxygen syntax).

Additionally, your code should work on at least Linux and Windows operating
systems. Portability is one main goal of PoDoFo, so it is important that the
code is always buildable and runnable on all supported platforms. We usually
test at least using GCC on Linux and using Visual Studio on Windows. Both
32bit and 64bit systems are target platforms. So if your code needs to work at
bit and byte-levels, take this into account.

Last but not least, all unit tests - especially test/unit/podofo-test - should
run after your modification. 


1. Submitting code
==================

If you are contributing code for the first time, the usual procedure is to
send a patch containing your modifications to the PoDoFo mailing list
<podofo-users@lists.sourceforge.net>. We will check your code and commit it
for you to the repository.

A patch should always be created against latest SVN trunk. Such a patch can be
created using  the SVN command "svn diff" on the commandline. 

It is recommended that you also add a unit test for the modification you have
made. If your modification is a bug fix, a unit test assures that no
regression for this bug is introduced at a later point of time (as everyone
runs the unit tests after every modification and before every commit). If you
added a new feature, the unit test guarantees that the new code was at least
tested once. Another very useful test is to run the test/ParserTest executable
and see if is able to parse and write the PDFReference1*.pdf from Adobe
correctly.

2. Getting a SVN account
========================

After we integrated some patches of yours successfully into SVN, you usually
can also get a SVN account. Feel free to ask for it, or if we think of it we
will offer an SVN account to you. Frequent submitters of patches are
encouraged to ask for an SVN account, as it is easier for everyone if
submitters of good quality patches can integrate these themselves.


3. Committing code
==================

Using a SVN account you can commit your code
yourself. If you are working on the main part of PoDoFo, you should announce
or discuss your intended changes on the mailing lists. If you are maintaining
a tool (under tools/) you can add features or make changes as you like.

An important point is that every commit has to go with a commit log message
that tells the other developers what your change does and why you made
it. These changes can be tracked and discussed on the PoDoFo SVN mailinglist
<podofo-svn@lists.sourceforge.net>. Every commit is automatically send to this
list.

4. Non-code contributions
=========================

Besides to code, we are also interested in other contributions like
documentation, feedback, examples, webpage, articles ...

Ask on the mailinglist if you are interested in helping or joining the
project.
