doc/release.org

   1 #+TITLE: Release Process for GNU Guile 2.0
   2 #+AUTHOR: Ludovic Courtès
   3 #+STARTUP: content
   4 #+EMAIL: ludo@gnu.org
   5
   6 This document describes the typical release process for Guile 2.0.
   7
   8 * Preparing & uploading the tarball
   9
  10 ** M-x debbugs-gnu
  11
  12 … or http://bugs.gnu.org/guile, for an idea of things to fix.
  13
  14 ** Update Gnulib
  15
  16 The commit log's first line should be "Update Gnulib to X", where X is
  17 the output of `git describe' in the Gnulib repo.
  18
  19 This allows us to keep track of the source code we use, in case a bug or
  20 security vulnerability gets fixed in Gnulib sometime later.
  21
  22 Ideally update Gnulib several days prior to the release, so that
  23 portability or build issues can be uncovered in time.
  24
  25 ** Make sure it works, portably, and with different configurations
  26
  27 *** Check [[http://hydra.nixos.org/jobset/gnu/guile-2-0][Hydra]]
  28
  29 This contains builds and cross-builds on different platforms, with
  30 different `configure' switches, different CPPFLAGS, and different
  31 versions of the compiler.
  32
  33 As of this writing, there are unfixed failures.  For instance Darwin's
  34 compiler randomly crashes, preventing build completion; the FreeBSD 7.x
  35 box experiences Guile crashes while running the test suite, which were
  36 not fixed because not reproduced elsewhere.  Even for these platforms,
  37 make sure "things don't get worse", at least.
  38
  39 *** Check [[http://autobuild.josefsson.org/guile/][Autobuild]]
  40
  41 This contains build reports from other people, typically on lesser used
  42 platforms, so it's worth checking.
  43
  44 *** Use the [[http://gcc.gnu.org/wiki/CompileFarm][GCC Compile Farm]]
  45
  46 Use the GCC Compile Farm to check on lesser used architectures or
  47 operating systems.  In particular, the Farm has ARM, SPARC64, PowerPC,
  48 and MIPS GNU/Linux boxes (remember that this is not superfluous: Debian
  49 builds on 11 architectures).  It also has FreeBSD and NetBSD boxes.
  50
  51 *** Use porter boxes
  52
  53 If you're still in a good mood, you may also want to check on porter
  54 boxes for other OSes.  The GNU/Hurd people have [[http://www.gnu.org/software/hurd/public_hurd_boxen.html][porter boxes]], and so do
  55 the [[http://www.opencsw.org/standards/build_farm][OpenCSW Solaris Team]] and the [[http://lists.gnu.org/archive/html/autoconf/2012-11/msg00039.html][Snakebite]] project.
  56
  57 *** Post a pre-release announcement to `platform-testers@gnu.org'
  58
  59 Send a link to [[http://hydra.nixos.org/job/gnu/guile-2-0/tarball/latest/download-by-type/file/source-dist][the latest tarball]].  This will allow readers to test on
  60 possibly weird platforms and report any bugs.
  61
  62 ** Update `GUILE-VERSION'
  63
  64 For stable releases, make sure to update the SONAME appropriately.  To
  65 that end, review the commit logs for libguile in search of any C ABI
  66 changes (new functions added, existing functions deprecated, etc.)
  67 Change `LIBGUILE_INTERFACE_*' accordingly.  Re-read the Libtool manual
  68 if in doubt.
  69
  70 `libguile/libguile.map' should also be updated as new public symbols are
  71 added.  Ideally, new symbols should get under a new version
  72 symbol---e.g., `GUILE_2.0.3' for symbols introduced in Guile 2.0.3.
  73 However, this has not been done for Guile <= 2.0.2.
  74
  75 ** Tag v2.0.x
  76
  77 Create a signed Git tag, like this:
  78
  79   $ git tag -s -u MY-KEY -m "GNU Guile 2.0.X." v2.0.X
  80
  81 The tag *must* be `v2.0.X'.  For the sake of consistency, always use
  82 "GNU Guile 2.0.X." as the tag comment.
  83
  84 ** Push the tag and changes
  85
  86   $ git push && git push --tags
  87
  88 Normally nobody committed in the meantime.  ;-)
  89
  90 ** Run "make distcheck"
  91
  92 This should trigger an `autoreconf', as `build-aux/git-version-gen'
  93 notices the new tag.  Make sure you have configured with all options
  94 enabled (Readline, --enable-deprecated, etc.)
  95
  96 After "make distcheck", double-check that `./configure --version'
  97 reports the new version number.
  98
  99 ** Upload
 100
 101   $ ./build-aux/gnupload --to ftp.gnu.org:guile guile-2.0.X.tar.gz
 102
 103 You'll get an email soon after when the upload is complete.
 104
 105 Your GPG public key must be registered for this to work (info
 106 "(maintain) Automated Upload Registration").
 107
 108 Make sure to publish your public key on public OpenPGP servers
 109 (keys.gnupg.net, pgp.mit.edu, etc.), so that people can actually use it
 110 to check the authenticity and integrity of the tarball.
 111
 112 ** Download
 113
 114 Make sure the file was uploaded and is available for download as
 115 expected:
 116
 117   $ mkdir t && cd t && \
 118     wget ftp.gnu.org/gnu/guile/guile-2.0.X.tar.gz && \
 119     wget ftp.gnu.org/gnu/guile/guile-2.0.X.tar.xz
 120   $ diff guile-2.0.X.tar.gz ../guile-2.0.X.tar.gz
 121   $ diff guile-2.0.X.tar.xz ../guile-2.0.X.tar.xz
 122
 123 You're almost done!
 124
 125 * Announcements
 126
 127 First, re-read the GNU Maintainers Guide on this topic (info "(maintain)
 128 Announcements").
 129
 130 ** Update web pages
 131
 132   - Replace any references to the previous version number and replace it
 133     with the new one.
 134   - Update news.html.
 135
 136 ** Update the on-line copy of the manual
 137
 138 Use `build-aux/gendocs', add to the manual/ directory of the web site.
 139
 140   $ cd doc/ref
 141   $ ../../build-aux/gendocs.sh guile "GNU Guile 2.0.X Reference Manual"
 142
 143 ** Prepare the email announcement
 144
 145   $ build-aux/announce-gen --release-type=stable --package-name=guile \
 146       --previous-version=2.0.1 --current-version=2.0.2 \
 147       --gpg-key-id=MY-KEY --url-directory=ftp://ftp.gnu.org/gnu/guile \
 148       --bootstrap-tools=autoconf,automake,libtool,gnulib,makeinfo \
 149       --gnulib-version=$( cd ~/src/gnulib ; git describe )
 150
 151 The subject must be "GNU Guile 2.0.X released".  The text should remain
 152 formal and impersonal (it is sent on behalf of the Guile and GNU
 153 projects.)  It must include a description of what Guile is (not everyone
 154 reading info-gnu may know about it.)  Use the text of previous
 155 announcements as a template.
 156
 157 Below the initial boilerplate that describes Guile should come the
 158 output of `announce-gen', and then the `NEWS' file excerpt in its
 159 entirety (don't call it a change log since that's not what it is.)
 160
 161 ** Send the email announcement
 162
 163 Send to these places, preferably in the morning on a working day (UTC):
 164
 165   - guile-user@gnu.org, guile-devel@gnu.org, guile-sources@gnu.org
 166   - info-gnu@gnu.org (for stable releases only!)
 167   - comp.lang.scheme
 168
 169 ** Post a news item on [[http://sv.gnu.org/p/guile/][Savannah]]
 170
 171 The news will end up on planet.gnu.org.  The text can be shorter and
 172 more informal, with a link to the email announcement for details.
 173
 174
 175 \f
 176 Copyright © 2011, 2012, 2013 Free Software Foundation, Inc.
 177
 178   Copying and distribution of this file, with or without modification,
 179   are permitted in any medium without royalty provided the copyright
 180   notice and this notice are preserved.