+-*-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.
system should be called Godot: "This is the one you've been waiting
for."
-Before releasing the next version of libguile which is not binary compatible
-with the one released with 1.4:
-- remove struct members system_transformer and top_level_lookup_closure_var
- from struct scm_root_state in root.h.
-
-After signal handling and threading have been fixed:
-- remove the code corresponding to GUILE_OLD_ASYNC_CLICK and the corresponding
- GUILE_OLD_ASYNC_CLICK macro.
-
-In release 1.5:
-- remove deprecated variables:
- scm_top_level_lookup_closure_var
-- remove deprecated functions:
- eval.c: scm_eval2, scm_eval_3
- load.c: scm_read_and_eval_x
-- remove deprecated procedures:
- boot-9.scm:eval-in-module
-- remove deprecated macros: SCM_INPORTP, SCM_OUTPORTP, SCM_CRDY, SCM_ICHRP,
- SCM_ICHR, SCM_MAKICHR, SCM_SETJMPBUF, SCM_NSTRINGP, SCM_NRWSTRINGP,
- SCM_NVECTORP
-- remove gc-thunk (It has been replaced by after-gc-hook.)
-- remove scm_sysmissing
-- remove gh_int2scmb (replaced by gh_bool2scm)
-- remove scm_fseek (replaced by scm_seek)
-- remove scm_tag
-- remove code related to the name property of hooks. Also, check init.c,
- since the dependency between hooks and objprop will then be eliminated.
-- remove deprecated function scm_list_star/list* (use SRFI-1 compliant
- scm_cons_star/cons* instead.)
-- remove scm_tc16_flo, scm_tc_flo (guile always uses doubles to represent
- inexact real numbers)
-- remove scm_tc_dblr (replaced by scm_tc16_real)
-- remove scm_tc_dblc (replaced by scm_tc16_complex)
-- remove deprecated types, functions and macros from numbers.h: scm_dblproc,
- SCM_UNEGFIXABLE, SCM_FLOBUFLEN, SCM_INEXP, SCM_CPLXP, SCM_REAL, SCM_IMAG,
- SCM_REALPART, scm_makdbl, SCM_SINGP, SCM_NUM2DBL, SCM_NO_BIGDIG
-
-In release 1.6:
-- remove deprecated macros: SCM_OUTOFRANGE, SCM_NALLOC, SCM_HUP_SIGNAL,
- SCM_INT_SIGNAL, SCM_FPE_SIGNAL, SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL,
- SCM_ALRM_SIGNAL, SCM_GC_SIGNAL, SCM_TICK_SIGNAL, SCM_SIG_ORD,
- SCM_ORD_SIG, SCM_NUM_SIGS
-- remove function scm_call_catching_errors
- (replaced by catch functions from throw.[ch])
-
-
-Modules sort.c and random.c should be factored out into separate
-modules (but still be distributed with guile-core) when we get a new
-module system.
-
Platforms for test builds:
SunOS (gcc and pcc) --- galapas.ai.mit.edu
Solaris (gcc and SUN cc) --- saturn.ai.mit.edu
mips-sgi-irix6.3
sparc-sun-sunos4.1.4
-Ian Grant <I.A.N.Grant@damtp.cam.ac.uk>:
-
- alpha-dec-osf4.0e
-
-Julian Satchell <satchell@merry.dra.hmg.gb>:
-
- dec-mips-ultrix
-
Perry Metzger <perry@piermont.com>
NetBSD
Release Checklists ===================================================
-There are basically two phases to doing a release:
+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
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 "Punting" phase you do only once.
+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:
-* Do a `cvs update -A', to get rid of any sticky tags in your working
- directory.
+* 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.
+
* 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 and the docs are up to date:
+
+* 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.
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.
+
* Rebuild all generated files in the source tree:
- + Install the .m4 files where aclocal will find them.
- + Run aclocal.
- + Run autoconf.
- + Run autoheader.
- + Run automake.
+ + run ./autogen.sh
+
* Verify that Guile builds and runs in your working directory.
-* Run the test suite, in guile-core/test-suite.
+
+* Run a "make check".
+
* Commit all changes to the CVS repository.
+
* Build a test distribution.
+
+ + update GUILE-VERSION each time you make a test distribution. For
+ example, just before the 1.6.0 release, we went through some
+ number of 1.5.X test releases.
+
+ BEFORE doing 'make dist', configure the source tree for build
- in the same tree with configuration options
- --enable-maintainer-mode --enable-debug-malloc --with-threads.
+ 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 steps are not done, the dependencies won't be properly
included in the generated Makefile.in files.)
+
+ Then do '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.)
+
* Give the test disty to various people to try. Here's what you should do:
+ Unset GUILE_LOAD_PATH.
+ Remove automake and autoconf from your path, or turn off their
Once you've got a disty that seems pretty solid:
-* Choose new interface numbers for shared libraries.
-* Update the version numbers in GUILE-VERSION and README. (There are
- many places in README that need updating!) The Guile version
- number should have one of the following forms:
- N.M - a major release
- N.M.L, where L is even - a minor release
- N.M.L, where L is odd - sources from CVS or nightly snapshot
+* 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 update -A' of the whole tree, to look for any stray
+
+* 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 N.M released." entry to the top-level ChangeLog, and commit it.
-* Tag the entire source tree with a tag of the form "release_N_M"
- or "release_N_M_L".
+* 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.
-* Tweak the version numbers in GUILE-VERSION, and README to indicate
- that the sources are a snapshot again. Snapshots should have
- version numbers of the form "N.M.L", where L is odd.
-* Start a new section of the NEWS file.
-* Start a new THANKS file.