"README.maintainer"
	$Id: README.maintainer,v 1.4 2007/07/31 23:22:25 fang Exp $

This document provide some useful information for HACKT developers, 
also useful to some of those who wish to contribute or modify the sources.  

-------------------------------------------------------------------------------
For CVS instructions, please refer to "README.CVS".  
For a list of things to verify before checking in revisions, 
please refer to "MAINTAINER-checklist".

===============================================================================
Makefiles:

This section describes the use of Make.stddef and Make.global makefile
fragments.  Make.stddef is a makefile header whose purpose is to 
define project-wide macros for popular command-line utilities, and to 
initialize standard macro variables that are used to accumulate 
over a makefile, e.g. CLEANFILES.  This relieves one of remembering
where the first definition of some common variables are -- if it's
common, it belongs in Make.stddef.  Make.stddef should be the first
thing included by other makefiles, either directly or indirectly.  
Make.global contains common project-wide Makefile targets.  By including
this at the end of each makefile, you automatically inherit a bunch of
useful targets.  Some of the targets depend on variables that accumulate
since their initializations in Make.stddef, such as AUTO_IGNORE.  
Make.global should be the last make-fragment included in any makefile.  

-------------------------------------------------------------------------------
CVS tags:

If you have cvs read access, then you can select specific versions and 
releases of the art++ package.  

The standard tag names are: ARTXX-##-##-## (for pre-HACKT revisions)
	or HACKT-##-##-## for all new revisions, 
	where ## is a 2 digit number (including leading zeros).  
Eventually, branch tags wil be introduced by appending
	-BRANCHNAME-##-## to the tag names.  
	The first -## of the branch name may be optional, 
	it is sometimes useful to reuse the same branch name with
	a different number to signify a new epoch of revisions with
	the same theme.  

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvsignore (a phony make target to make .cvsignore recursively)

CVS ignore files (.cvsignore) are all semi-automatically generated
in this project.  The rationale behind this is that automake already
knows most of the files that should be ignored because they are 
built (although there are always exceptions).  The Makefile system
uses AUTO_IGNORE as a cumulative list of files to automatically ignore.  
In addition, the generated .cvsignore files depend on a local.cvsignore
file from which it acquires user-defined (non-automatic) files.  
local.cvsignore is also where wildcard patterns belong.  
The local.cvsignore file may also be automatically generated by other 
means, e.g., copying from an existing .cvsignore.  
In all cases, "make cvsignore" creates .cvsignore recursively for all
listed subdirectories, and "make clean-cvsignore" removes them.  

===============================================================================
COMMIT CHECKLIST

For developers, guidelines of things TODO when checking in revisions.  
When in doubt, email one of the maintainers.  

DEVELOPMENT COMMITS:
	make && 
	make check.log && 
	make distcheck.log
		This MUST pass for commits to the main trunk to guarantee
		some sort of stability and functionality at all times.  
		Commits along branches are more forgiving and may allow
		for commits that transiently break things, but such known
		breaks should be noted as such in the ChangeLog entry.  
	src/ChangeLog is the primary source revision log and should be 
		updated with an entry upon every commit.  The new entry should 
		start with the new CVS Tag, incremented from the previous one.  
		If there is no revision in the src/ directory, then just
		note "no source revision" and reference the other locations
		where there was a revision, e.g. test, lib, dox...
		exception: tiny or obvious patches need not be tag-bumped
			but should be re-tagged using last tag (cvs tag-move):
			cvs tag -F <same tag name>
	configure.ac:
		The version date need not be bumped with every commit.
		Occasionally a maintainer will bless a particular snapshot
		with a date-bump, which says that "this snapshot has been
		more rigorously tested than others."  
	ChangeLog: $(top_srcdir)
		This needs to be updated only when top-level maintainence
			files are updated, such as automake, autoconf, 
			configure/m4 scripts, or other organization stuff.


BRANCH CREATION:
	Obviously need to 'cvs tag -b <name>' to create the branch.  
	The branch name must contain the name of the tag from which it is
		derived, for ease of tracking.  
		Also applies to sub-sub-branches.
	First src/ChangeLog entry along the branch should summarize the 
		purpose of the branch.  
	Add a one-line entry about the branch to the BRANCHES file
		and commit that to the MAIN TRUNK, so there's a record
		of the branches existence.  

BRANCH MERGES: (merging branch-to-trunk)
	CVS Tag: 
		In addition to the tag number incrementing, the new tag on the 
		main trunk should be suffixed with "-merged-branchname-revision"
		to indicate up to which point of the branch has been 
		merged to trunk.  This helps track the status of various
		branches.  
	src/ChangeLog:
		The ChangeLog should state that a particular branch is 
		terminated if no further developement is *intended* along 
		the branch.  
	BRANCHES: if this is the last merge of the branch to trunk, 
		then retire the branch by deleting its entry from this file.


BACKPORTS (TRUNK MERGES): (from trunk-to-branch)
	This usually applies when backporting a single patch to a branch, 
	in which case, the tag should be labeled: -backport-main-##-...
		where the number corresponds to the tag-suffix on the trunk.
	The patch for the tag is acquired by cvs diff -r <tag-1> -r <tag>.
		where -1 means the previous tagged revision.  
	For a cumulative trunk backport, use "-backport-upto-main-##".
	For a selected revision range, use "-backport-from-...-to-..."

RELEASE-CANDIDATES:
	(Decide whether or not they belong on branch or trunk.)
	Tag

RELEASE:
	All COMMIT checklist items apply.  In addition:
	If possible, check for the following items in a release-check script.  
	configure.ac: 
		remove the "-devel" string from the version string
			for OFFICIAL releases (none have happened yet).  
		bump the version date to present.  
	branch:
		A release series is isolated from the main development line, 
		thus all revisions relative to a release belong on a release
		branch.  The branch should be named with -RELEASE instead
		of -main-xx...
	shared library versioning: (not applicable yet)
		bump library version numbers, following standard
			library versioning convention (GNU libtool).  
	default AM_CFLAGS and AM_CXXFLAGS:
		turn OFF paranoid and strict developer flags as the default 
		compile options because users may use untested compilers.
		After release, remember to turn developer flags back on.
	ChangeLog: announce release
	NEWS: announce release

RELEASE-BRANCH COMMITS:
	Release branches will continue to receive bug fixes and documentation
		improvements, but no other classes of source revisions.  
	CVS Tags: (numbering convention)

===============================================================================

