PKG-SNF4CGP-NIX/ReadMe

20090324_M First stab at describing the structures and dev rules
we will employ on our SVN server. I'm sure this will evolve ;-)

This is the repository startup readme. When we create a new SVN
repository on the svn.microneil.com server we populate it with
this ReadMe file so there is something useful to check out the
first time.

This ReadMe should be replaced when the repository is populated.

There probably should be a ReadMe file in the root of /trunk/
so that folks using the repository understand what is there and
what rules apply to the project.

Projects (repositories) should be structured according to the
following rules:

** In general the root of /trunk/ for any project should be as
empty as possible containing at most the ReadMe file and possibly
the most current "golden version" of the project's goal. 

All rules have exceptions and the exception to this rule is the
first project type (below) - source libraries. 
__________________________________________
For Source Code Modules / Source Libraries:
The /trunk/ should contain just the source code, data, ReadMe,
and other parts that are considered part of the module. Modules
are meant to be re-used and so they will be imported as external
SVN references in other projects where they are consumed.

We would expect to see something like:

/trunk/source.h
/trunk/source.cpp
/trunk/ReadMe

In general, source modules are imported by external reference and
are never manipulated directly for themselves. For example, while
developing a source library the repository for that source would be
externally referenced by a Test module (below). The developer would
build the test application while exercising the source library and
making changes to that library (presumably in a branch). When they
are satisfied that their updates are working correctly according
to the test application they would commit the Test module project
and the imported source module project.

_______________________
For Test (DEV-) Modules:
Test modules are special applications that exercise other modules.
They are also, essentially, applications so they share the application
model. The /trunk/ should contain a sub directory that holds the
source code specific to the test application. Other modules that are
under testing and development are referenced as svn:external so that
they reside under /trunk/ as additional source directories.

We should expect to see something like:

svn:external /Module/trunk Module
/trunk/Tester/source.h
/trunk/Tester/source.cpp
/trunk/Tester/docs/stuff-to-read
/trunk/Tester/data/stuff-to-input
/trunk/tester/data/stuff-to-output
/trunk/ReadMe

In the above example interpret Module to be the appropriate name for
a source library. There can be as many of these re-usable components
as needed. Note that they don't actually appear in the SVN server but
since they are a property of the repository they will be checked out
when this repository is checked out so they will appear in the local
file system at the same level as Tester.

______________________________________
For Applications or Compiled Libraries:

Similarly to Test Modules (above) the root of /trunk/ should contain
ReadMe describing what is there and how it works. ALSO, however the
final product of the build will be at the root of /trunk/. This will
represent the current state-of-the-art for the application. It may be
a .DLL file, a .o, a .a etc.

Subdirectories under /trunk/ contain the source directories, test
application sources (in the case of a binary or library type project
such as a DLL, .o, .a, .exe or other binary).

Presumably the developer would create a workspace on their local
file system where they would then import the repository's /trunk/ and
along with it the associated external references. Then in a different
directory in their workspace they would build various debug and
production versions of the final product for testing. When they were
happy with the results then they would place the new "golden" version
in their local copy of the repository and commit (repository, and
externals with any changes, and new golden version).

Develpers of applications or binary libraries should avoid the urge
to make direct updates to source libraries. That work should be done
separately where it can be well focused.

________________________________
For Distribution (PKG-) Pakages:

Distribution packages are used to build distributions that are released
to customers. The package includes everything that is needed to build
the final distribution (tarball, zip) and/or installer (.msi, .exe)
file that will be delivered to customers.

Distribution pakages follow a similar methodology to Applications
except that they most likely reference specific revisions of libraries,
projects, and documentation, and then combine that with subdirectories
that contain package specific content such as documentation, build
scripts, and other "glue".

In the top directory we expect to find the usual ReadMe for the project
as well as the latest golden version of the distribution.

The build process and structure here is much the same as for other
applications except that what is tested is the ability to deliver and /
or install the application on the various target platforms with the
desired results. The applications themselves are always built elsewehere
in their own projects even though the repositories for those projects
might be imported in their entirety via external references.

Developers of distribution packages should avoid the urge to make
updates to the applications or other imported content directly. That
work should be handled seperately where it can be focused.