guile/RELEASE

-*-text-*-
This is a checklist for making Guile releases.
It's specific to the FSF's development environment; please don't put
it in the distribution.

Maybe we should name Guile releases after entertaining poisons:
absinthe, etc.  However, the first release containing the module
system should be called Godot: "This is the one you've been waiting
for."

Platforms for test builds:
SunOS (gcc and pcc) --- galapas.ai.mit.edu
Solaris (gcc and SUN cc) --- saturn.ai.mit.edu
NetBSD (gcc) --- repo-man.ai.mit.edu (use /home/repo/jimb)
HP/UX (gcc, HP cc) --- nutrimat.gnu.ai.mit.edu

These gentlemen have kindly offered to do pre-release testing:

Tom Tromey <tromey@cygnus.com>:

  alphaev5-unknown-linux-gnu
  hppa1.1-hp-hpux10.20
  hppa1.1-hp-hpux11.00
  mips-sgi-irix5.3
  powerpc-ibm-aix4.2.0.0
  powerpc-unknown-linux-gnu
  sparc-sun-solaris2.6
  i686-pc-linux-gnu
  mips-sgi-irix6.3
  sparc-sun-sunos4.1.4

Perry Metzger <perry@piermont.com>

  NetBSD


Release Checklists ===================================================

There are basically three phases to doing a release:

* "BRANCHING": Creating a stable development branch in CVS.

* "SPIFFING": Updating NEWS, README, INSTALL.  Running tests.  Getting
  people to try builds on various machines.  Getting everything
  straightened up.

* "PUNTING": Updating the version numbers.  Tagging the sources.  Asking
  the FSF to put the disty on ftp.gnu.org.  Posting announcements.

The "Spiffing" phase you might go through several times as you
discover problems.  The "Branching" and "Punting" phases you do only
once.

Branching checklist:

* Announce when you're about to make the branch so that you have a
  greater chance of people holding off on edits during the short
  period while you're branching.

* Make sure you're on the main trunk (see HACKING), and then create
  the branch-root tag.  i.e. -r branch-root_release-1-6.  (Add the
  exact command here next time I do it.)

* Now create the branch with the branch tag. i.e. -r
  branch_release-1-6.  (Add exact command here next time I do it.)

* Change the version numbers in GUILE-VERSION and README on the main
  branch to reflect the new unstable version i.e. 1.7.0, if you're
  currently creating the 1.6.X branch.

Spiffing checklist:

  NOTE: Unless you're *SURE* you know what you're doing, please
  perform the following actions in order.  The ordering is important
  in places below.

* Make sure you're working on the stable branch (see HACKING for
  details).  Note that after following the branch checklist above, you
  won't necessarily be.

* Make sure you've got the latest files "cvs -qz3 update -Pd".

* Check for files that have changed a lot, but do not have up-to-date
  copyright notices.  This can be as simple as doing:
 	grep 'Copyright' * | grep -v 1999
  and looking for files you know you've worked on a lot.

* Make sure NEWS, INSTALL, AUTHORS and THANKS and the docs are up to date:
  + Scan the ChangeLogs for user-visible changes, marked with an asterisk
    at the left margin.
  + Update NEWS and the Texinfo documentation as appropriate.
  + Remove the user-visible markers from the log entries once they're
    documented.
  + Check for any [[incomplete]] sections of NEWS.
  + Fact-check INSTALL.
  + Make sure AUTHORS and THANKS are up-to-date (see also TODO).
  + Remove finished items from TODO (those marked w/ "+").

* Make sure the downloading addresses and filenames in README are
  current.  (But don't bump the version number yet.  We do that below.)

* Check that the versions of aclocal, automake, autoconf, and autoheader
  in your PATH match those given in HACKING.  Note that the `make
  dist' process always invokes these tools, even when all the
  generated files are up to date.
  Make specifically sure that the files in libltdl are generated using
  the same tools as the rest.

* Run ./autogen.sh to rebuild all generated files in the source tree.

* Build the test distribution

  NOTE: during this section, don't commit any of your changes to CVS
  until the instructions tell you to below.  This is important so that
  someone doesn't check out CVS and think that they have a finished
  copy of a particular release when they actually don't.

  * update GUILE-VERSION to reflect the current test distribution, but
    don't commit this change to CVS yet (see below).  For example,
    just before the 1.6.0 release, we went through some number of
    1.5.X test releases.

  * configure the source tree for build in the same tree with these
    configuration options:
      --enable-maintainer-mode --enable-debug-malloc --with-threads
      --enable-error-on-warning

  * Make sure that readline was enabled correctly.

  * Build the tree.  (If the above two steps are not done first, the
    dependencies won't be properly included in the generated
    Makefile.in files.)

  * Verify that Guile builds and runs in your working directory.

  * Run a "make check".

  * Run 'make dist'.

  * Check that the dependencies in guile-readline/Makefile look OK.
    (We currently use a kludge which edits the dependencies generated
    by automake so that Guile can be built in a directory separate
    from the source tree also with non-GNU make programs.)

  * Add a "Guile beta N.M released." entry to the top-level ChangeLog.

  * Now commit all your changes to CVS.

  * Tag the release "cvs tag release_1-5-2".

  * Run 'make dist' again to get the official tarfile.

* Test the tarfile yourself using the instructions under "Testing a
  release candidate tarfile" below.

* Give the test disty to various people to try.  They should follow
  the same instructions under "Testing a release candidate tarfile"
  below.

* Testing a release candidate tarfile:
  + Unset GUILE_LOAD_PATH.
  + Remove automake and autoconf from your path, or turn off their
    execute bits, or something.  (Users must be able to build the
    disty without installing those tools.)
  + Configure, make, and install.
  + Make sure LD_LIBRARY_PATH doesn't include anything unnecessary.
  + Run the test suite on the installed version.
  + You might try the example code in the doc directory.

Once you've got a disty that seems pretty solid:

* Make sure the shared library libtool versioning numbers are correct,
  but first make sure you understand "Libtool's versioning system" in
  the libtool info pages.  Guile is going to be versioning it's shared
  libraries independently, so follow the libtool rules for choosing
  version numbers, but make sure to keep in mind that not everyone is
  as good about this as they should be.  If a library even changes the
  layout of a data structure that's part of it's API in a backward
  incompatible way, even if that data structure is handled as an
  opaque object in the API, that library is probably no longer
  compatible with previous versions.

  A canonical ugly problem is this.  Imagine you have libfoo and
  libbar that both are linked against libbaz.  Now imagine that you
  create a libwhatever that uses both libfoo and libbar.  What you
  don't want to have happen is libfoo and libbar to be linked against
  different versions of libbaz that produce incompatible instances of
  the "same" data structure, and then have libwhatever get one version
  of this data structure from libbaz via libfoo, and pass it back to a
  different version of libbaz via libbar, a version of libbaz that
  can't handle the newer/older struct from the other libbaz.

* In general, there will be a number of libraries in guile that will
  have to be versioned, and it would be best if the people who know
  the most about the individual libs decide what the apropriate
  CURRENT, REVISION, and AGE numbers for each one are.  In general,
  though, you have to be conservative.  If no one is sure that the
  libs are still compatible, then you *must* make the appropriate
  changes under the assumption that they're not.  Getting this wrong
  is very BAD(TM).

* Make the final update to the version numbers in GUILE-VERSION and
  README.  (There are many places in README that need updating!).  See
  HACKING for more information on how the version numbers are to be
  chosen.

* Reformat the names in THANKS.

* Do a `cvs -z3 update -Pd' of the whole tree, to look for any stray
  uncommitted or accidental changes.

* Commit your changes.

* Make one last test distribution.

Punting checklist:

* Add "Guile X.Y.Z released." entry to the top-level ChangeLog, and commit it.

* Tag the entire source tree with a tag of the form "release_X-Y-Z",
  i.e for release 1.6.0, use release_1-6-0

* Do a 'make dist'.

* Put the distribution up for FTP somewhere, and send mail to
  ftp-upload@gnu.org, asking them to put it on prep.

* Send an announcement message to gnu-announce@gnu.org.  Put a brief
  summary of the changes in this release first, then "Obtaining
  Guile", "Thanks", "About This Distribution," and "Nightly
  Snapshots."  If I remember correctly, the moderator will delay it
  until the distribution appears on ftp.gnu.org.  The announcement
  text should be mostly taken from Guile's README file.

* Notify freshmeat.net, although they're probably watching anyway.
  (They got the 1.3 release just fine.)  I have no idea if
  www.bowerbird.com.au will be something anyone refers to, but Guile
  does have an entry there.