RELEASE

   1 -*-text-*-
   2 This is a checklist for making Guile releases.
   3 It's specific to the FSF's development environment; please don't put
   4 it in the distribution.
   5
   6 Maybe we should name Guile releases after entertaining poisons:
   7 absinthe, etc.  However, the first release containing the module
   8 system should be called Godot: "This is the one you've been waiting
   9 for."
  10
  11 Platforms for test builds:
  12 SunOS (gcc and pcc) --- galapas.ai.mit.edu
  13 Solaris (gcc and SUN cc) --- saturn.ai.mit.edu
  14 NetBSD (gcc) --- repo-man.ai.mit.edu (use /home/repo/jimb)
  15 HP/UX (gcc, HP cc) --- nutrimat.gnu.ai.mit.edu
  16
  17 These gentlemen have kindly offered to do pre-release testing:
  18
  19 Tom Tromey <tromey@cygnus.com>:
  20
  21   alphaev5-unknown-linux-gnu
  22   hppa1.1-hp-hpux10.20
  23   hppa1.1-hp-hpux11.00
  24   mips-sgi-irix5.3
  25   powerpc-ibm-aix4.2.0.0
  26   powerpc-unknown-linux-gnu
  27   sparc-sun-solaris2.6
  28   i686-pc-linux-gnu
  29   mips-sgi-irix6.3
  30   sparc-sun-sunos4.1.4
  31
  32 Ian Grant <I.A.N.Grant@damtp.cam.ac.uk>:
  33
  34   alpha-dec-osf4.0e
  35
  36 Julian Satchell <satchell@merry.dra.hmg.gb>:
  37
  38   dec-mips-ultrix
  39
  40 Perry Metzger <perry@piermont.com>
  41
  42   NetBSD
  43
  44
  45 Release Checklists ===================================================
  46
  47 There are basically three phases to doing a release:
  48
  49 * "BRANCHING": Creating a stable development branch in CVS.
  50
  51 * "SPIFFING": Updating NEWS, README, INSTALL.  Running tests.  Getting
  52   people to try builds on various machines.  Getting everything
  53   straightened up.
  54
  55 * "PUNTING": Updating the version numbers.  Tagging the sources.  Asking
  56   the FSF to put the disty on ftp.gnu.org.  Posting announcements.
  57
  58 The "Spiffing" phase you might go through several times as you
  59 discover problems.  The "Branching" and "Punting" phases you do only
  60 once.
  61
  62 Branching checklist:
  63
  64 * Announce when you're about to make the branch so that you have a
  65   greater chance of people holding off on edits during the short
  66   period while you're branching.
  67
  68 * Make sure you're on the main trunk (see HACKING), and then create
  69   the branch-root tag.  i.e. -r branch-root_release-1-6.  (Add the
  70   exact command here next time I do it.)
  71
  72 * Now create the branch with the branch tag. i.e. -r
  73   branch_release-1-6.  (Add exact command here next time I do it.)
  74
  75 * Change the version numbers in GUILE-VERSION and README on the main
  76   branch to reflect the new unstable version i.e. 1.7.0, if you're
  77   currently creating the 1.6.X branch.
  78
  79 Spiffing checklist:
  80
  81 * Make sure you're working on the stable branch (see HACKING for
  82   details).  Note that after following the branch checklist above, you
  83   won't necessarily be.
  84
  85 * Check for files that have changed a lot, but do not have up-to-date
  86   copyright notices.  This can be as simple as doing:
  87         grep 'Copyright' * | grep -v 1999
  88   and looking for files you know you've worked on a lot.
  89
  90 * Make sure NEWS, INSTALL, AUTHORS and THANKS and the docs are up to date:
  91   + Scan the ChangeLogs for user-visible changes, marked with an asterisk
  92     at the left margin.
  93   + Update NEWS and the Texinfo documentation as appropriate.
  94   + Remove the user-visible markers from the log entries once they're
  95     documented.
  96   + Check for any [[incomplete]] sections of NEWS.
  97   + Fact-check INSTALL.
  98   + Make sure AUTHORS and THANKS are up-to-date (see also TODO).
  99   + Remove finished items from TODO (those marked w/ "+").
 100
 101 * Make sure the downloading addresses and filenames in README are
 102   current.  (But don't bump the version number yet.  We do that below.)
 103
 104 * Check that the versions of aclocal, automake, autoconf, and autoheader
 105   in your PATH match those given in HACKING.  Note that the `make
 106   dist' process always invokes these tools, even when all the
 107   generated files are up to date.
 108   Make specifically sure that the files in libltdl are generated using
 109   the same tools as the rest.
 110
 111 * Rebuild all generated files in the source tree:
 112   + run ./autogen.sh
 113
 114 * Verify that Guile builds and runs in your working directory.
 115
 116 * Run a "make check".
 117
 118 * Commit all changes to the CVS repository.
 119
 120 * Build a test distribution.
 121   + update GUILE-VERSION each time you make a test distribution.  For
 122     example, just before the 1.6.0 release, we went through some
 123     number of 1.5.X test releases.
 124   + BEFORE doing 'make dist', configure the source tree for build
 125     in the same tree with configuration options
 126     --enable-maintainer-mode --enable-debug-malloc --with-threads.
 127   + Make sure that readline was enabled correctly.
 128   + Build the tree.
 129     (If the above steps are not done, the dependencies won't be properly
 130     included in the generated Makefile.in files.)
 131   + Then do 'make dist'.
 132   + Check that the dependencies in guile-readline/Makefile look OK.
 133     (We currently use a kludge which edits the dependencies generated
 134     by automake so that Guile can be built in a directory separate
 135     from the source tree also with non-GNU make programs.)
 136
 137 * Give the test disty to various people to try.  Here's what you should do:
 138   + Unset GUILE_LOAD_PATH.
 139   + Remove automake and autoconf from your path, or turn off their
 140     execute bits, or something.  (Users must be able to build the
 141     disty without installing those tools.)
 142   + Configure, make, and install.
 143   + Make sure LD_LIBRARY_PATH doesn't include anything unnecessary.
 144   + Run the test suite on the installed version.
 145   + You might try the example code in the doc directory.
 146
 147 Once you've got a disty that seems pretty solid:
 148
 149 * Make sure the shared library libtool versioning numbers are correct,
 150   but first make sure you understand "Libtool's versioning system" in
 151   the libtool info pages.  Guile is going to be versioning it's shared
 152   libraries independently, so follow the libtool rules for choosing
 153   version numbers, but make sure to keep in mind that not everyone is
 154   as good about this as they should be.  If a library even changes the
 155   layout of a data structure that's part of it's API in a backward
 156   incompatible way, even if that data structure is handled as an
 157   opaque object in the API, that library is probably no longer
 158   compatible with previous versions.
 159
 160   A canonical ugly problem is this.  Imagine you have libfoo and
 161   libbar that both are linked against libbaz.  Now imagine that you
 162   create a libwhatever that uses both libfoo and libbar.  What you
 163   don't want to have happen is libfoo and libbar to be linked against
 164   different versions of libbaz that produce incompatible instances of
 165   the "same" data structure, and then have libwhatever get one version
 166   of this data structure from libbaz via libfoo, and pass it back to a
 167   different version of libbaz via libbar, a version of libbaz that
 168   can't handle the newer/older struct from the other libbaz.
 169
 170 * In general, there will be a number of libraries in guile that will
 171   have to be versioned, and it would be best if the people who know
 172   the most about the individual libs decide what the apropriate
 173   CURRENT, REVISION, and AGE numbers for each one are.  In general,
 174   though, you have to be conservative.  If no one is sure that the
 175   libs are still compatible, then you *must* make the appropriate
 176   changes under the assumption that they're not.  Getting this wrong
 177   is very BAD(TM).
 178
 179 * Make the final update to the version numbers in GUILE-VERSION and
 180   README.  (There are many places in README that need updating!).  See
 181   HACKING for more information on how the version numbers are to be
 182   chosen.
 183
 184 * Reformat the names in THANKS.
 185
 186 * Do a `cvs -z3 update -Pd' of the whole tree, to look for any stray
 187   uncommitted or accidental changes.
 188
 189 * Commit your changes.
 190
 191 * Make one last test distribution.
 192
 193 Punting checklist:
 194
 195 * Add "Guile N.M released." entry to the top-level ChangeLog, and commit it.
 196
 197 * Tag the entire source tree with a tag of the form "release_X-Y-Z",
 198   i.e for release 1.6.0, use release_1-6-0
 199
 200 * Do a 'make dist'.
 201
 202 * Put the distribution up for FTP somewhere, and send mail to
 203   ftp-upload@gnu.org, asking them to put it on prep.
 204
 205 * Send an announcement message to gnu-announce@gnu.org.  Put a brief
 206   summary of the changes in this release first, then "Obtaining
 207   Guile", "Thanks", "About This Distribution," and "Nightly
 208   Snapshots."  If I remember correctly, the moderator will delay it
 209   until the distribution appears on ftp.gnu.org.  The announcement
 210   text should be mostly taken from Guile's README file.
 211
 212 * Notify freshmeat.net, although they're probably watching anyway.
 213   (They got the 1.3 release just fine.)  I have no idea if
 214   www.bowerbird.com.au will be something anyone refers to, but Guile
 215   does have an entry there.