-------------------------------------------------------------------------------
Information for developers and contributors
-------------------------------------------------------------------------------

This documentation shall give some hints to developers and contributors.
Please send comments and suggestions to the prozilla-dev mailinglist.


Coding guidelines
-----------------

  * Use an indentation width of 2 spaces.
    Braces are put on a separate line, not on the same line as the
    if/while/for etc. statements. The braces themselves are not indented, only
    the code within the braces.

    Example:

    if (foo == TRUE)
    {
      while (bar != NULL)
      {
        do_something("Test.", 19);
        do_something_else();
      }
    }
    else
    {
      printf("Foo is not TRUE.\n");
      exit(EXIT_SUCCESS);
    }

  * Put a space after each comma.

  * Do *not* put spaces between the function-name and the opening brace:
    Wrong: foo ("Test", 19);
    Correct: foo("Test", 19);

  * Do not put a space when referring to a pointer.
    Wrong: void foo(const char * message);
    Correct: void foo(const char *message);

  * Do not use any TABs in the code. The only files where you should use TABs
    is the ChangeLog and the Makefile.am's.

  * Write only 80 characters per line where possible.

Have a look at the already existing code for examples.


Names
-----

Always use good, unabbreviated, correctly-spelled meaningful names.

All functions, variables, enums, #defines etc. which are intended to be used
by the programs which link against libprozilla, are prefixed with proz_
or PROZ_.

Examples:
  proz_init();
  #define PROZ_MAX_CONNECTIONS 19
  etc.


TODO, FIXME and NOTE
--------------------

Use the keywords 'TODO', 'FIXME' and 'NOTE' in the source-code comments
to remind yourself or other developers of things which still need to be
done or fixed.

You can then do a simple 'grep TODO *.[ch]' to find all those comments...


ChangeLog entries
-----------------

Everytime you make a change to any of the files, you must write a ChangeLog
entry with your name, email adress and the date. Please try to write
verbosive comments and also give reasons why you wrote/changed something
if that reason is not obvious...

You can use 'cvs -z3 diff -Nu * | vim -' to view the differences between your
code and the latest CVS-code. Use this as a help to write the ChangeLog entry.

Changes to the file 'ChangeLog' can be omitted, because this file is changed
*everytime* anyway...

If you commit a patch from another developer or a contributor, add his name
and email-adress to the file AUTHORS. Also write a small message in the
ChangeLog which says e.g. 'Applied patch from Joe Foo <foo@bar.com>.'.

Do the same if someone reports and/or fixes a bug: Add him to AUTHORS and add
a ChangeLog entry, e.g. 'Fixed a bug reported by Joe Foo <foo@bar.com>.'.


Comments
--------

  * Do not comment obvious code (i++ /* Increment i. */ etc...).

  * Only use C-style comments (/* Foo. */) and not C++-style comments (// Foo.).

  * All comments should start with a capital letter and end with a dot.


Tools used
----------

We use the following tools for this project:

  * autoconf 2.13 or better
      ftp://ftp.gnu.org/gnu/autoconf/

  * automake 1.4 or better
      ftp://ftp.gnu.org/gnu/automake/


Code from other projects
------------------------

 * getopt.c, getopt.h:
   Purpose: Commandline options parsing code.
   Author: ???
   License: GPL.
   From: ftp://ftp.gnu.org/gnu/glibc/
   Comments: Unmodified version from glibc.

 * netrc.c, netrc.h:
   Purpose: Parse the .netrc file to get hosts, accounts, and passwords.
   Author: Gordon Matzigkeit <gord@gnu.ai.mit.edu>
   License: GPL
   From: ???
   Comments: Modified for libprozilla.

 * url.c, url.h:
   Purpose: URL handling code.
   Author: ???
   License: GPL.
   From: ???
   Comments: Modified for libprozilla.


Automatically generated files
-----------------------------

The following files are automatically generated by either aclocal, autoheader
autoconf or automake. Do not edit them directly.

Makefile.in
aclocal.m4
config.h.in
configure
install-sh
missing
mkinstalldirs
stamp-h.in
docs/Makefile.in
src/Makefile.in


common.h
--------

All libprozilla files include the common.h file. This file #includes all
headers we need, #defines some things like TRUE and FALSE, typedefs
a 'boolean' type etc...


Patches
-------

Send your patches (diff -u) to the prozilla-dev mailinglist.

If you changed several things in the code or fixed more than one problem,
please send a separate patch for each of the fixes. If everything is in one
single patch file, the patch is a lot harder to understand, check and apply. 


Mailinglists
------------

Read the README.


CVS
---

You can access the libprozilla CVS repository anonymously (read-only access)
by issueing the following commands:

cvs -d :pserver:anonymous@cvs.delrom.ro:/home/cvsroot login

Press enter when prompted for the password.

cvs -d :pserver:anonymous@cvs.delrom.ro:/home/cvsroot co libprozilla