prozilla/libprozilla/docs/HACKING
2010-08-31 03:50:41 +02:00

199 lines
5.0 KiB
Plaintext

-------------------------------------------------------------------------------
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