===================================
HACKING PHPESP: A Developer's Guide
===================================

This document contains a guide to the phpESP source code, and how to
get started as a developer.


INTRODUCTION
------------

If you are interested in working on or contributing to phpESP, please
read this entire document.  First of all, it is highly recommended that
you join the phpESP developer mailing list (follow the link on the
phpESP web site).  Please direct all discussion to this list.  Do _not_
send email to developers directly, you will probably be ignored.

OBTAINING PHPESP FROM CVS
-------------------------

phpESP comes in three flavors: there are stable release versions,
development (or beta) release versions, and the phpESP cvs tree.  Most
developers work directly with the most current sources in the cvs
tree.  In order to check out a working copy from the cvs tree, you must
have a cvs client.  You can login to the cvs server as "anonymous" to
get read-only access with the following command (all one line):

  $ cvs -d :pserver:anonymous@cvs.phpesp.sourceforge.net:/cvshome/phpesp
        login

The password is empty, so just press enter at the prompt.  Once you are
logged in, you can obtain a working copy of phpESP with the following
command (also all on one line):

  $ cvs -d :pserver:anonymous@cvs.phpesp.sourceforge.net:/cvshome/phpesp
        co phpESP

This will create a directory called "phpESP", which will contain the 
current sources.  You may work with these files by whatever means you
wish.  You may also use cvs commands within this directory to interact
with the cvs tree.  For example, to generate a patch including all
changes you have made to the source locally, you would execute (from
the "phpESP" directory):

  $ cvs diff -u

The output, called a unified diff, is the preferred format for sending
patches to the development team.  If you are not familiar with cvs, you
may read more about it at the following web site:

  http://www.cvshome.org/


SOURCE CODE LAYOUT
------------------

The layout of non-code files should be pretty self-explanatory, if you
have any questions about where to add a file please ask on the
developer mailing list.

The majority of the the code for phpESP is under the admin/include/
directory.  There are four subdirectories in include/ which divide the
code into four categories.  The function/ subdirectory contains files
that essentially define one function.  You should consider adding a
file here if you are defining a new function that is very long.  The
lib/ subdirectory contains files which contain several related
functions.  For example, lib/espresponse.inc contains several functions
that are used for the manipulation of survey responses.  The tab/
subdirectory contains files responsible for the presentation and layout
of each of the tabs in the survey editor.  Finally, the where/
directory contains files responsible for the presentation and layout of
each of the pages available in the administration interface.  Files
from this directory are loaded and executed according the the form
variable 'where'.  For example, when you open the following URL

  http://localhost/phpESP/admin/manage.php?where=status

The phpESP framework will load all the support functions from the
function/ and the lib/ directories, then pass execution off to
where/status.inc.

In general, if you are adding a new page to the administration
interface, the code should go into the where/ directory.  If you are
adding a support function, the code belongs in the function/ or lib/
directory.  The goal of this layout is to keep as much code out of the
where/ directory as possible to help separate code and content.


CODING STANDARDS
----------------

Please follow the PEAR Coding Standards as closely as possible when
contributing code to phpESP.  These standards are available at

  http://pear.php.net/manual/en/standards.php

You may ignore the PEAR standard for 'Header Comment Blocks,' please do
not add any License comments to the source without approval.

Please refrain from reformatting existing code, except in areas very
close to where you are making changes.  Reformatting code makes merging
changes from other branches much more difficult.  Under certain
circumstances, it may be appropriate (or necessary) to reformat code;
please consult the developer mailing list before any significant
reformatting.


PATCHES, FEATURES, AND BUGS
---------------------------

All patches should be sent to the developer mailing list, with a
subject beginning with '[patch]', and the patch included as an
attachment (not in-line).  Please include a description of your patch,
and any other pertinent information in the body of your email.

All features and bugs should be reported by using the SourceForge
trackers.  Any transaction in either of these trackers is posted to the
developer mailing list, so there is no need to announce them
separately.  Also note that any additions to tracker items should be
made via the web interface, because the replication is one way (changes
on the web are sent to the list, but not vice versa).


ETIQUETTE
---------

phpESP is a volunteer based project; please remember this, and remember
that the developers all have 'day jobs.'  Please try to keep all
correspondence courteous and professional.  Also, please keep relevant
discussions on the mailing lists; email directly to one of the
developers is likely to be ignored.  If you do not get a reply on the
mailing list, try finding one of the developers on IRC (refer to the
phpESP web site for IRC channel information), or repost your email.


BECOMING AN "OFFICIAL" DEVELOPER
--------------------------------

If you have major changes or enhancements to make, or have submitted
several accepted patches, you may be considered to become an "official"
developer.  This status grants one commit access to the phpESP cvs
repository.  Anyone who wishes to become an official developer should
send a request to the developer mailing list with a short
justification.

----
$Id: HACKING,v 1.1.1.1 2005/08/10 12:14:03 yoshis Exp $
