guile/doc/release.org

#+TITLE: Release Process for GNU Guile 3.0
#+AUTHOR: Ludovic Courtès
#+STARTUP: content
#+EMAIL: ludo@gnu.org

This document describes the typical release process for Guile 3.0.

* Preparing & uploading the tarball

** M-x debbugs-gnu

… or http://bugs.gnu.org/guile, for an idea of things to fix.

** Optionally, Update Gnulib

The commit log's first line should be "Update Gnulib to X", where X is
the output of `git describe' in the Gnulib repo.

This allows us to keep track of the source code we use, in case a bug or
security vulnerability gets fixed in Gnulib sometime later.

Ideally update Gnulib several days prior to the release, so that
portability or build issues can be uncovered in time.

** Make sure it works, portably, and with different configurations

*** Check [[https://ci.guix.gnu.org/jobset/guile][continuous integration]]

This contains builds and cross-builds on different platforms, with
different `configure' switches, different CPPFLAGS, and different
versions of the compiler.

You can also build things with Guix locally by running commands from the
top-level such as:

#+begin_example
  guix build -f guix.scm
  guix build -f guix.scm -s i686-linux
  guix build -f guix.scm --target=aarch64-linux-gnu
  guix build -f guix.scm --target=x86_64-w64-mingw32
#+end_example

*** Optionally, test portability to other CPUs and OSes

  - Use the [[https://gcc.gnu.org/wiki/CompileFarm][GCC Compile Farm]] to check on lesser used architectures or
    operating systems.  In particular, the Farm has ARM, SPARC64,
    PowerPC, and MIPS GNU/Linux boxes (remember that this is not
    superfluous: Debian builds on 11 architectures).  It also has
    FreeBSD and NetBSD boxes.
  - The GNU/Hurd people have [[http://www.gnu.org/software/hurd/public_hurd_boxen.html][porter boxes]] (better yet: you can use a
    [[https://guix.gnu.org/manual/devel/en/html_node/Virtualization-Services.html#index-childhurd_002c-offloading][childhurd]] on Guix System), and so does the [[http://www.opencsw.org/standards/build_farm][OpenCSW Solaris Team]].
  - You can also send a link to the latest tarball to [[https://lists.gnu.org/mailman/listinfo/platform-testers][platform-testers]].
    This will allow readers to test on possibly weird platforms and
    report any bugs.

** Update `GUILE-VERSION'

For stable releases, make sure to update the SONAME appropriately.  To
that end, review the commit logs for libguile in search of any C ABI
changes (new functions added, existing functions deprecated, etc.)
Change `LIBGUILE_INTERFACE_*' accordingly.  Re-read the Libtool manual
if in doubt.

`libguile/libguile.map' should also be updated as new public symbols are
added.  Ideally, new symbols should get under a new version
symbol---e.g., `GUILE_3.0.3' for symbols introduced in Guile 3.0.3.

** Tag v3.0.x

Create a signed Git tag, like this:

  $ git tag -s -u MY-KEY -m "GNU Guile 3.0.X." v3.0.X

The tag *must* be `v3.0.X'.  For the sake of consistency, always use
"GNU Guile 3.0.X." as the tag comment.

** Push the tag and changes

  $ git push && git push --tags

Normally nobody committed in the meantime.  ;-)

** Run "make distcheck"

This should trigger an `autoreconf', as `build-aux/git-version-gen'
notices the new tag.  Make sure you have configured with all options
enabled (Readline, --enable-deprecated, etc.)

After "make distcheck", double-check that `./configure --version'
reports the new version number.

** Upload

  $ ./build-aux/gnupload --to ftp.gnu.org:guile guile-3.0.X.tar.{lz,xz,gz}

You'll get an email soon after when the upload is complete.

Your GPG public key must be registered for this to work (info
"(maintain) Automated Upload Registration").

Make sure to publish your public key on public OpenPGP servers
(keys.gnupg.net, pgp.mit.edu, etc.), so that people can actually use it
to check the authenticity and integrity of the tarball.

** Download

Make sure the file was uploaded and is available for download as
expected:

  $ mkdir t && cd t && \
    wget ftp.gnu.org/gnu/guile/guile-3.0.X.tar.gz && \
    wget ftp.gnu.org/gnu/guile/guile-3.0.X.tar.xz
  $ diff guile-3.0.X.tar.gz ../guile-3.0.X.tar.gz
  $ diff guile-3.0.X.tar.xz ../guile-3.0.X.tar.xz

You're almost done!

* Announcements

First, re-read the GNU Maintainers Guide on this topic (info "(maintain)
Announcements").

** Update web pages

  - Update the version number in ‘latest-guile-version’ in the (website
    utils) module of the [[https://git.savannah.gnu.org/cgit/guile/guile-web.git][web site]].
  - Add a news item by dropping a Markdown file under =posts/=.
  - Build the web site: =haunt build=.
  - Synchronize the files under site/ over the CVS repo.

** Update the on-line copy of the manual

Use `build-aux/gendocs', add to the manual/ directory of the web site.

  $ cd doc/ref
  $ ../../build-aux/gendocs.sh guile "GNU Guile 3.0.X Reference Manual"

** Prepare the email announcement

  $ build-aux/announce-gen --release-type=stable --package-name=guile \
      --previous-version=3.0.1 --current-version=3.0.2 \
      --gpg-key-id=MY-KEY --url-directory=ftp://ftp.gnu.org/gnu/guile \
      --bootstrap-tools=autoconf,automake,libtool,gnulib,makeinfo \
      --gnulib-version=$( cd ~/src/gnulib ; git describe )

The subject must be "GNU Guile 3.0.X released".  The text should remain
formal and impersonal (it is sent on behalf of the Guile and GNU
projects.)  It must include a description of what Guile is (not everyone
reading info-gnu may know about it.)  Use the text of previous
announcements as a template.

Below the initial boilerplate that describes Guile should come the
output of `announce-gen', and then the `NEWS' file excerpt in its
entirety (don't call it a change log since that's not what it is.)

** Send the email announcement

Send to these places, preferably in the morning on a working day (UTC):

  - guile-user@gnu.org, guile-devel@gnu.org, guile-sources@gnu.org
  - info-gnu@gnu.org (for stable releases only!)
  - comp.lang.scheme




Copyright © 2011, 2012, 2013, 2017, 2018, 2025 Free Software Foundation, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.