README.developers

	README.developers - Instructions for developers with CVS access.


Pre-Requisites:

This package is configured and built with GNU Autoconf 2.57 or newer
and GNU Automake 1.7 or newer.  They require Perl-5.005 or newer.


Initial Builds:

In order to pre-build the necessary config files from a freshly checked
out repository you must run the following commands in the given order:

	autoreconf -f -i

Now you can proceed with the normal build process (./configure && gmake).

Note that running "gmake maintainer-clean" should remove all files that
are not stored in CVS -- i.e. all those that will be re-created by the
above sequence of commands.

(You'll note the above instructions use 'gmake' -- GNU Automake
makefiles are designed to work best with GNU Make, especially for
various configuration maintenance tasks, though the *BSD 'pmake'
version usually works fine too, except for some VPATH builds.)


Making a New Release:

In order to build releases you *MUST* be using a version of GNU Automake
that includes support for proper CVS-based release management using the
'make dist' approach.

New releases should be adequately tested, of course, and you should
check that all changes have been commited to CVS.  The "NEWS" file
should be checked to ensure it has been updated with notes about all
user-visible changes.  If you're making a full release you can coalesce
any entries from previous alpha and beta releases.  If there's a GNATS
PR category for the project you should check that there are no absolute
"show-stopper" bugs in the pending release.

To test the build system and to test the entire package run:

	autoreconf -f -i
	./configure
	gmake distcheck

This will create a trial distribution archive, extract it in a
sub-directory, configure it, build it (using a reach-over VPATH build),
run any tests (gmake check), and install it in another private
sub-directory.  WARNING:  You _must_ use 'gmake' for the this particular
target -- BSD Pmake fails in the 'make dist-gzip' part of the VPATH
build because for some unknown reason it tries to update the "source"
version of "$(DIST_MAKE)" files instead of creating them in the build
directory.

To clean up after "gmake distcheck" you may need to give yourself
permissions on the directory (sometimes the ${PACKAGE}-${VERSION}
directory is not removed as it has been made read-only):

	sh
	. ./VERSION
	chmod -R u+rw ${PACKAGE}-${VERSION}
	rm -rf ${PACKAGE}-${VERSION}
	rm -f ${PACKAGE}-${VERSION}.tar.gz
	exit

Once you're ready to more widely test your release, and you've commited
any and all changes you've made, check the "VERSION" identifier in the
file VERSION again.  After each release it should have been updated file
by setting it to the next expected release and then appending a
"-Preview.0" suffix to it so as to keep any trial distribution copies
clearly identifiable.  Don't forget to check in any change to the
VERSION file right away.  You may also want to "cvs tag" each trial
distribution of your preview releases as well, but it's not really
necessary unless multiple people will be co-operating with the testing.

	cat VERSION

Once this is all done run "gmake distcheck" again to create the actual
preview release distribution.  Immediately afterwards you should
increment the trailing number after the "-Preview" suffix on the
"VERSION" identifier in the VERSION file and check in this change.  The
idea is to keep the checked-in "VERSION" identifier one ahead of the
most recently created (trial) distribution.  This is especially
important if you publish or distribute the trial distribution in any
way, and of course this is extremely important if multiple people are
working on the project -- you want their next update to show an
unreleased version identifier so as not to confuse anything they build
with your (trial) distribution.

	autoreconf -f -i
	./configure
	gmake distcheck
	sh
	. ./VERSION
	mv ${PACKAGE}-${VERSION}.tar.gz ~ftp/pub/preview
	chmod -R u+rw ${PACKAGE}-${VERSION}
	rm -rf ${PACKAGE}-${VERSION}
	exit
	vi VERSION
	cvs commit -m '- another preview release starts' VERSION

You should now copy this preview release distribution to other types of
machines and platforms and build and check it there too.

Once you think you're ready to try an actual release, update the
"VERSION" identifier in the VERSION file (see the notes below on release
numbers), and check this in.

	cat VERSION
	vi VERSION
	sh
	. ./VERSION
	cvs commit -m '- time to release $VERSION' VERSION
	exit

To tag, export, and create the final distribution archive you need to
run the following commands (assuming you've already run the initial
GNU Auto* commands detailed above):

	sh	# start a sub-shell to make resetting env easier
	place_to_build_releases=/work/woods/release.d	# for example
	gmake distclean
	. ./VERSION
	tag=$(echo $VERSION | tr . _)
	cvs tag -c ${PACKAGE}-${tag} .
	export CVSROOT=$(cat CVS/Root)
	cd $place_to_build_releases
	cvs export -kv -r ${PACKAGE}-${tag} -d ${PACKAGE}-${VERSION}-export $PACKAGE
	cd ${PACKAGE}-${VERSION}-export
	autoreconf -f -i
	sh ${PACKAGE}2netbsd.sh		# configures best default paths...
	rm -rf import.d			# clean up after ${PACKAGE}2netbsd.sh
	gmake dist			# or distcheck
	mv ${PACKAGE}-${VERSION}.tar.gz ..
	gmake distclean
	cd ..
	pax -rzf ${PACKAGE}-${VERSION}.tar.gz
	diff -r --brief ${PACKAGE}-${VERSION}-export ${PACKAGE}-${VERSION}

The last step ensures that everything in the CVS module is distributed.

If the 'diff' command reveals any files are missing then you need to go
back, untag the whole module, fix Makefile.am, and re-test.

If all goes well you can put $PACKAGE-$VERSION.tar.gz up for access and
copy the new project page sub-files into place with this command:

	rcp ${PACKAGE}-${VERSION}.tar.gz ftp:~ftp/pub/local # scp doesn't do ~
	cd $place_to_build_releases/${PACKAGE}-${VERSION}
	sh ${PACKAGE}2netbsd.sh		# redo -- after distclean
	gmake update-project-web-files

	# optionally update your NetBSD source trees too!
	cd import.d
	cp * /usr/src/usr.bin/${PACKAGE}/

	# if all is OK you can clean up the release directories too:
	cd $place_to_build_releases
	rm -rf ${PACKAGE}-${VERSION}-export ${PACKAGE}-${VERSION}
	exit

Now update the actual project page in ~/public_html/projects/$PACKAGE.html

Lastly post an update on http://freshmeat.net/


After Making a New Release:

IMPORTANT:  Immediately after you've published a successfull new release
don't forget to update the "VERSION" identifier in the VERSION file to
indicate the pre-release of the next most likely release (e.g. set
1.0.0.80-Preview.0 after making 1.0).  See below for release number
ideas.

If you plan on maintaining one or more maintenance releases using
branches then you should instead create a release branch for every N.N
release and set the "VERSION" to N.N.0.80-Preview.0 on the branch and
N.N+1.80-Preview.0 on the trunk.


Release Numbers:

We essentially follow the basics of the Berkeley CSRG version numbering
scheme for identifying releases.  That is to say we increment the third
number (3.7, 3.7.1, 3.7.2, etc.) whenever we generate a release of bug
fixes (what might traditionally be also known as a "patch" release), and
we increment the second number, or the minor release number, (3.7, 3.8)
whenever we add any new features or make other important user-visible
changes, and lastly we increment the first number, or the major release
number, (3.*, 4.1) whenever we make major or architectural changes.

We also throw in a smattering of GNU-isms too -- the beta-test and
release candidates (RCs) of upcoming proper releases should have a
".80" or ".90" (respectively) appended to the current release number
(3.7.5.80 would be the first beta for 3.7.6, continuing with 3.7.5.81,
3.7.5.82, etc., 3.7.5.90 would be the first release candidate,
continuing with 3.7.5.91, 3.7.5.92, etc. until finally 3.7.6 is
released.

Beta releases are the "you asked for this feature, I think this is a
good implementation of it, try it out, but there may be more to come
before the next release" releases.

Release Candidates (RCs) are created once you think you've reached a
more stable and release-ready stage which means "all the features
which will be in the next release are now in, and have undergone at
least some testing and if nobody finds any (major show-stopping) bugs,
this will be the next release."

One special case rule not yet described covers the releases preceding
the initial release, which would might start with semi-private releases
numbered "0.x", e.g. 0.1.80, 0.1.90, 0.1.91, 0.2, 0.2.80, 0.2.90, 0.3,
etc., then full public releases numbered "1.0.x", e.g. 1.0.80, 1.0.90,
etc. until 1.1, the first fully official release is made.

Note that there are no ".0" releases!  I.e. ".0" is only used as a
separator between initial major releases and the first minor release,
and between initial minor releases and the first patch release.

I.e. you only insert a ".0" when you start a new branch!

Ideally patch releases will be developed on a release branch to permit
parallel development of new features on the trunk for the next minor (or
major) release (with folding of fixes and features as necessary back to
the trunk).  In theory minor releases could also be developed on release
branches, but only in situations where extreme levels of maintenance for
existing releases must be undertaken.

You'll note this effectively caps the maximum number of releases along
any patch branch to a ceiling of ".79", and limits the number of alpha
releases at any level to just 10.  Unfortunately it does not limit the
number of beta releases since things like .100 are allowed!  ;-)

Some projects require developers to keep track of ABI or API changes
along the trunk (e.g. so that others tracking trunk development can be
made aware of when they are about to cross, or have already crossed,
some line which might require special procedures to adapt their
environment to the change).  Marking of these application interface
changes can be dealt with by modifying the beta scheme so that ".80"
always starts the new development of these changes and then for each
cange one appends an incrementing suffix number to the ".80" starter
number.  The first true beta release would then be ".81".  ABI changes
could be marked this way along any line of development and even after
first beta, but for practical purposes they should be restricted to
the trunk (i.e. only done for major and minor releases) and only done
prior to the initial beta release if at all possible (i.e. ".81.1"
should not be allowed unless absolutely necessary, and ".9x.1" should
be forbidden at all cost).  I.e. any time you want to make an ABI
change then that's a very good time to begin at least a new minor
release, if not a new major release.  If you can't fix something
without making an interface change then it's time to abandon that
branch.

If you see "-Preview.N" appended to the release number then you're
seeing an intermediate development copy -- i.e. an as-yet un-released
copy which will likely have the release number given with the suffix
stripped when it is finally officially released.

A complete example:

	0.0		project concept published

		0.0.80		begin initial development
		0.0.80.1	after first ABI change
		0.0.80.2	after second ABI change
		...
		0.0.90		pre-release RC #1
		0.0.91		pre-release RC #2
		...
		0.1		first pre-release

		0.1.80		begin second pre-release
		0.1.80.1	after ABI change
		...
		0.1.90		2nd pre-release RC #1
		0.1.91		2nd pre-release RC #2
		...
		0.2		second pre-release

		...

	1.0.80		begin first official release
	1.0.80.1	after an ABI change
	1.0.80.2	after an ABI change
	...
	1.0.81		first beta
	...
	1.0.90		first official release candidate
	1.0.91		second official release candidate
	1.0.92		third official release candidate
	...

	1.1	first official (major) release

			1.1.0.80	begin branch development
					(no ABI changes should be allowed)
			1.1.0.81	1st beta
			...
			1.1.0.90	1st RC for first patch
			1.1.0.91	2nd RC for first patch
			....
			1.1.1		first patch release

			1.1.1.80
			1.1.1.81
			...
			1.1.1.90
			1.1.1.91
			...
			1.1.2		second patch release

			1.1.2.80
			1.1.2.81
			...
			1.1.2.90
			1.1.2.91
			...
			1.1.3		third patch release

			...

			[1.1.79]	last possible patch release

		(begin 1.2 on trunk in parallel with the 1.1.0 patch branch)
		1.1.80		begin minor release
		1.1.80.1	after ABI change
		1.1.80.2	after ABI change
		1.1.80.3	after ABI change
		....
		1.1.81		first beta
		...
		1.1.90		second official release RC #1
		1.1.91		second official release RC #2
		...

		1.2	second official (minor) release

			1.2.0.80	begin branch development
			1.2.0.81	1st beta
			...
			1.2.0.90	1st RC for first patch
			1.2.0.91	2nd RC for first patch
			...
			1.2.1		first patch release

			1.2.1.80
			1.2.1.81
			...
			1.2.1.90
			1.2.1.91
			...
			1.2.2		second patch release

			1.2.2.80
			1.2.2.81
			...
			1.2.2.90
			1.2.2.91
			...
			1.2.3		third patch release

			...

			[1.2.79]	last possible patch release

		(begin next minor on trunk in parallel with 1.2.0 patch branch)
		1.2.80
		1.2.80.1
		
		. . . and so on to 1.3, 1.4, etc. . . .

	(to start a new major release we pretend to "branch" the trunk)

	2.0.80		begin new major release
	2.0.80.1	after ABI change
	2.0.80.2	after ABI change
	2.0.80.3	after ABI change
	...
	2.0.81		first beta
	...
	2.0.90		first RC
	2.0.91		second RC
	...

	2.1	second major release

			2.1.0.80	begin branch development
			2.1.0.81	1st beta
			...
			2.1.0.90	1st RC for first patch
			2.1.0.91	2nd RC for first patch
			....
			2.1.1		first patch release

			2.1.1.80
			2.1.1.81
			...
			2.1.1.90
			2.1.1.91
			...
			2.1.2		second patch release

			2.1.2.80
			...
			2.1.2.90
			2.1.2.91
			...
			2.1.3		third patch release

			...

		(in parallel with the 2.1.0.80 patch branch)
		2.1.80		begin next minor release
		2.1.80.1	after ABI change
		2.1.80.2	after ABI change
		2.1.80.3	after ABI change
		....
		2.1.81		first beta
		...
		2.1.90		second official release candidate
		2.1.91		second official release candidate
		...

		2.2	next official (minor) release

			2.2.0.80	begin branch development
			2.2.0.81	1st beta
			...
			2.2.0.90	1st RC for first patch
			2.2.0.91	2nd RC for first patch
			...
			2.2.1		first patch release

			2.2.1.80
			2.2.1.81
			...
			2.2.1.90
			2.2.1.91
			...
			2.2.2		second patch release

			2.2.2.80
			2.2.2.81
			...
			2.2.2.90
			2.2.2.91
			...
			1.2.3		third patch release

		2.2.80		begin next minor release
		2.2.80.1
		...

		2.3

	3.0.80

Starting new major releases might look like it adds another branch,
but it's only a conceptual branch.  At any point along the trunk when
it's decided that the next release will be called a "major" release
then the current X.N.8n.x beta or X.N.9n.x release candidate is simply
promoted to become (X+1).0.[89]n.x, just as in my example above.  We
really only create branches in the source code control system in order
to maintain patch releases in parallel with ongoing development on the
trunk and we don't maintain minor releases in parallel with the
development of a new major release.  In a volunteer project it's
already asking a lot just to use branches for patch releases, let
alone minor releases.


NOTE:  This file *is* included in distributions so that users and
contributors can see how all the release magic works!

#ident	"@(#)newsyslog:README.developers:$Format:%D:%ci:%cN:%h$"