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