README.developers - Instructions for developers with CVS access.
Pre-Requisites:
This package is configured and built with GNU Autoconf 2.53 or newer and GNU Automake 1.6 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:
aclocal
autoheader && touch config.h.in
automake --gnu --add-missing --copy
autoreconf --force
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:
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.
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 VERSION. 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.
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.
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.
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} .
cd $placeto_build_releases
cvs export -kv -r ${PACKAGE}-${tag} -d ${PACKAGE}-${VERSION}-export $PACKAGE
cd ${PACKAGE}-${VERSION}-export
aclocal
autoheader
automake --gnu --add-missing
autoreconf --force
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:
cd $place_to_build_releases/${PACKAGE}-${VERSION}
gmake update-project-web-files
# if all is OK you can clean up the release directories too:
cd $place_to_build_releases
rm -rf ${PACKAGE}-${VERSION}-export ${PACKAGE}-${VERSION}
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 essence 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 alpha-test and beta-test releases 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 alpha for 3.7.6, continuing with 3.7.5.81, 3.7.5.82, etc., 3.7.5.90 would be the first beta, continuing with 3.7.5.91, 3.7.5.92, etc. until finally 3.7.6 is released; for another example the first alpha for 4.1.1 would be 4.1.0.80, continuing with 4.1.0.81, 4.1.0.82, etc., 4.1.0.90 would be the first beta, continuing with 4.1.0.91, 4.1.0.92, etc., until finally 4.1.1 is released).
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.
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 patch level, and the maximum minor release number, to a ceiling of ".79", and limits the number of alpha releases to just 10. Unfortunately it does not limit the number of beta releases since things like .100 are allowed! ;-)
For projects that require it for developers to keep track of ABI changes along the trunk, they can be dealt with by modifying the beta scheme so that ".80" starts the new development, and then appending an incrementing suffix number to the ".80" starter number. The first true beta release would then be ".81". ABI changes could be handled along any line of development, but for practical purposes they should be restricted to the trunk.
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 ABI change
1.0.80.2 after 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 release
1.1.0.80 begin branch development
1.1.0.81 1st beta
...
1.1.0.90 1st release candidate
1.1.0.91 2nd release candidate
....
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
(in parallel with the 1.1.0.80 patch branch)
1.2.0.80 begin minor release
1.2.0.80.1 after ABI change
1.2.0.80.2 after ABI change
1.2.0.80.3 after ABI change
....
1.2.0.81
...
1.2.0.90 second official release beta #1
1.2.0.91 second official release beta #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 release candidate
1.2.0.91 2nd release candidate
...
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.3.0.80 begin next minor (in parallel with 1.2.0.80)
1.3.0.80.1
. . . and so on to where we are now with 1.6 . . .
2.0.80 begin new major release (bump trunk)
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 release candidate
2.1.0.91 2nd release candidate
....
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
2.2.0.80 begin next minor release
2.2.0.80.1 after ABI change
2.2.0.80.2 after ABI change
2.2.0.80.3 after ABI change
....
2.2.0.81 first official beta
...
2.2.0.90 second official release candidate
2.2.0.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 release candidate
2.2.0.91 2nd release candidate
...
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.3.0.80 begin next minor release
2.3.0.80.1
3.0.80
This might look like it adds another branch, but it doesn't have to. It just depends on whether you want to bump the trunk to start the next major release, or whether you do want to go out on a branch for minor releases. If you want to bump the trunk then at any point along the trunk when it's decided that the next release will be called a "major" release then 1.N.0.80.x can be promoted to become 2.0.80.x, just as in my example above. 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:newsyslog-1_1:README.developers,v 1.14 2003/07/08 16:49:01 woods Exp"