ABOUT
=====

This branch is a reorganization of the bitcoin source code (the actual
behavior of the code has not been changed).  It is based on the
0.3.21beta (commit b37f09aa2e80b17028ad7fe1e87362c0f07c7406) sources.
The main intent of this commit is to solicit input and review of the
organization.  Much work remains to finish the reorganization, get it
easily building across all supported platforms and to document it.  This
readme file is a brief overview of the work thus far and what remains to
be done.

Note: while the sources are in sync with the latest commit on the master
bitcoin branch, the autotool have not been taught how to build with
USE_UNPNP enabled.

Classes are now organized into their own source code files.  For each
class there is a header file that declares the class, a header file that
has any inline or template definitions, and a source file for the method
implementations.  For a class named "CFoo" (class names always begin
with a letter "C" by convention), the corresponding source files would
be named:

    CFoo.h - header with the class declaration 
    CFoo-inl.h - header with inline and template methods (if any) 
    CFoo.cpp - method implementations

The primary header file will include the inline header file at the end
(if there is one).  The header files use the typical #ifndef/#define
pattern to use the pre-processor to ensure any given class header is
only processed once by the compiler.  In the header files, where
possible, forward declarations of referenced classes are used rather
than including the other class' header file.  A policy of one class per
*.h, *-inl.h, *.cpp is followed with the exception of exception classes
(currently there are two, bignum_error and key_error).  The exception
classes follow the main class declaration in the file of the class that
uses them.  In a couple of cases, this results in rather small files
that one might be tempted to fold into another class' files.  In the
interest of consistency, even these small classes have been put into
their own set of files (again, exception classes are the only exception
to this rule).

While the classes have been separated into their own files and should be
pretty clean, the non object oriented source files and headers are still
a bit of a mess and in need of cleanup.  Header file include statements
need to be pruned.

Autotools have been introduced in the build process in order to simplify
the configuration and make files and provide more automatic dependency
management (i.e. include file dependencies are automatically tracked
such that touching any given header file would only force a recompile of
exactly those source files that include it, directly or indirectly). 
Autotools should also enable one set of configuration and make files to
be used across platforms, but this is not yet the case. The use of
autotools will also enable source code distributions to be built (make
dist) and enable packaging for popular package management tools (rpm,
ports, apt, etc).

At this point, this code has only been compiled on Mac OSX.  To
successfully compile, you will need to follow the instructions for
building from the main branch to compile all of the dependencies (i.e.
BDB, wxWidgets, etc) and then follow the usual autotools approach to
building.  There is a script in this directory for rebuilding the
configure script and make files (autogen.sh).  After running that
script, then run "./configure; make" ("make install" isn't supported
yet).  Both the daemon and full GUI have been successfully compiled.

Remaining work (in rough priority order):

1. Sync up with the head of the master bitcoin source code branch (this
code is based on 0.3.20.2) --DONE

2. Organize the non class based sources by grouping related functions
together and relocated source files into subdirectories (likely subdirs
would be peer, gui, cli, wallet, miner, and common) <--- I could use
suggestions on which functions/classes belong in which of these logical
packages

3. Clean up the non class based sources and headers and prune header
file includes

4. Eliminate the use of -DGUI for building the GUI

5. Clean up the comments & copyright statements, etc

6. Make it compile cleanly across all platforms


Development process
===================

Developers work in their own trees, then submit pull requests when they think their feature or bug fix is ready.

If it is a simple/trivial/non-controversial change, then one of the bitcoin development team members simply pulls it.

If it is a more complicated or potentially controversial change, then the patch submitter will be asked to start a discussion (if they haven't already) on the development forums:  http://www.bitcoin.org/smf/index.php?board=6.0
The patch will be accepted if there is broad consensus that it is a good thing.  Developers should expect to rework and resubmit patches if they don't match the project's coding conventions (see coding.txt) or are controversial.

The master branch is regularly built and tested (by who? need people willing to be quality assurance testers), and periodically pushed to the subversion repo to become the official, stable, released bitcoin.


Feature branches are created when there are major new features being worked on by several people.


CODING STANDARDS
================

Please be consistent with the existing coding style.

Block style:

bool Function(char* psz, int n)
{
    // Comment summarising what this section of code does
    for (int i = 0; i < n; i++)
    {
        // When something fails, return early
        if (!Something())
            return false;
        ...
    }

    // Success return is usually at the end
    return true;
}

- ANSI/Allman block style
- 4 space indenting, no tabs
- No extra spaces inside parenthesis; please don't do ( this )
- No space after function names, one space after if, for and while

Variable names begin with the type in lowercase, like nSomeVariable.
Please don't put the first word of the variable name in lowercase like
someVariable.

Common types:
n       integer number: short, unsigned short, int, unsigned int,
            int64, uint64, sometimes char if used as a number
d       double, float
f       flag
hash    uint256
p       pointer or array, one p for each level of indirection
psz     pointer to null terminated string
str     string object
v       vector or similar list objects
map     map or multimap
set     set or multiset
bn      CBigNum

Classes:

Classes should be separated into their own *.h, *-inl.h and *.cpp files
using the class name for the base of the filename (class names should
begin with the letter "C").  The *.h file should contain only the class
declaration.  The definitions of any inline and template members belongs
in *-inl.h and should be included from the *.h file (near the end).  The
header file should be guarded with the typical #ifndef/#define pattern
to ensure it is only included once.  The one exception to this rule are
exception classes, who's declaration and definitions can be placed in
the files of the class that uses them (declare the main class first,
followed by the exception class(es)).