8.8 KiB

Raw Blame History

Release Process for GNU Guix

Update NEWS
Prepare & upload tarball
Announcements

This document describes the typical release process for Guix.

Update NEWS

Update the list fixed bugs, with bugs.gnu.org URL

Run "git log" and search for "^Fixes".

Update the list of new and updated packages

Run “make update-NEWS”.

This target needs requires a checkout of <git://git.savannah.gnu.org/guix/maintenance.git>, which is where we store the list of package/version pairs of each Guix release.

The update-NEWS script expects some sections to already exist such as '* new packages' and '* package updates' that are to be updated.

Commit the new list of packages in maintenance.git

Running “make update-NEWS” creates a data/packages-X.Y.Z.txt file in your maintenance.git checkout. Make sure to commit it:

git add data/packages-X.Y.Z.txt git commit -m "Data for X.Y.Z."

Prepare & upload tarball

Create branch 'version-X.Y.Z'

$ git branch version-X.Y.Z $ git checkout version-X.Y.Z

Enter a guix environment containing everything needed

The documentation has a few extra requirements:

$ guix environment guix –ad-hoc imagemagick perl

Bootstrap and build

If you haven done so already, the build system should be initialized using:

$ ./bootstrap && ./configure –localstatedir=/var –sysconfdir=/etc

and the project should be built with something like:

$ make -j$((2 * $(nproc)))

Add a Git tag

Create a signed Git tag, like this:

$ git tag -s -u MY-KEY -m "GNU Guix X.Y.ZrcN." vX.Y.ZrcN $ autoreconf -f # to update $(PACKAGE_VERSION)

Use “rcN” for release candidates, drop it otherwise.

The tag must be vX.Y.Z. For the sake of consistency, always use GNU Guix X.Y.Z as the tag comment. The autoreconf -f invocation is important, and should be re-run anytime you create a new tag.

Update the translation files

In a nutshell, to update the translation files, you can run:

$ make download-po

$ make

$ autoreconf -f

If there are any new translation files, commit them following the guidelines in (guix)Translating Guix. For the remaining changes, it's OK to simply do:

$ git add po $ git commit -m 'nls: Update translations.'

Run “make release” for one or several release candidates

This will automatically build:

The source tarball, with make dist (commit V).
The binary tarballs for each architecture, after first updating the guix package in (gnu packages package-management) so that it uses the commit above (we’re now at V + 1).
The Guix System installation images, after first updating the guix package again to refer to the 2nd commit above (we’re now at V + 2).

All these files will end up in a release-X.Y.Z sub-directory.

Needless to say, this operation takes some time. Since this is committing on your behalf, it will contact your gpg-agent to sign commits, so you need to keep an eye on it or to increase the time-to-live for cached passphrases in ~/.gnupg/gpg-agent.conf (do that only if your machine is in a safe place!):

Caveat: If the release target fails, you'll be left in the middle of something which cannot be resumed from where it stopped. You can try to debug the underlying commands that failed, but after fixing the problem, you should remove any automatic commits that were done to update the guix package and try again.

  default-cache-ttl 36000
  max-cache-ttl 36000

Steps #2 and #3 require you to have offloading set up so you can build for all the supported architectures. For instance, if you’re running this on an x86_64 machine, you should have armhf-linux, aarch64-linux and powerpc64le-linux machines in your /etc/guix/machines.scm. Transparent emulation via QEMU has shown limits (such as causing test suite failures); real hardware is a must.

Push the branch

If “make release” succeeded, push the branch and tag:

$ git push

Merge the version-X-Y-Z branch into master

It's recommended to not alter the history at this time, so that the release tag will be reachable directly from the master branch (and visible in git describe).

Upload all the files

The gnupload script from Gnulib is used to upload the release artifacts to the GNU FTP. It requires the ncftp package to be installed. For a final release, the following should be used:

$ cd release-X.Y.Z $ gnupload –to ftp.gnu.org:guix *.[xlg]z *.qcow2 *.iso

To uploading a release candidate (RC), the /guix/maintenance/src/commit/96d7a212207166149797319504742e6431db0899/doc/alpha.gnu.org URL should be used instead, like so:

$ cd release-X.Y.Z $ gnupload –to alpha.gnu.org:guix *.[xlg]z *.qcow2 *.iso

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.

Add a Cuirass jobset for branch 'version-X.Y.Z'

This jobset will have to be kept until the next release, so that substitutes remain available. The easiest way to add a new jobset is directly via the web interface of Cuirass. To be allowed to do so, you must authenticate with the Cuirass instance via a private TLS certificate imported into your browser.

Generate a TLS user certificate for Cuirass

On the Berlin machine, do the following:

$ sudo /root/maintenance/hydra/cuirass-client-certs/create.sh ${USER}

Then retrieve the generated certificate from /etc/ssl-ca/certs/users/${USER}.p12 to your personal device and import it into your browser.

You can now navigate to https://ci.guix.gnu.org/ and click the + button to configure the new job specification. For more information regarding specifications, see https://guix.gnu.org/cuirass/manual/cuirass.html#Specifications.

Announcements

First, re-read the GNU Maintainers Guide on this topic.

Update web pages

Update the ‘latest-guix-version’ value in (apps base utils), in the guix-artwork.git repository. Add a blog post under posts/.

The web site will be automatically rebuilt by an mcron job on berlin (every hour).

Update the on-line copy of the manual

Change the ‘static-web-site’ service in hydra/berlin.scm (guix-maintenance.git) and reconfigure berlin, so that it builds the ‘version-X.Y.Z’ branch.

Note: Simply reconfiguring is not enough to ensure the new manual will be built. You must also restart the mcron service for the update job to take effect.

Prepare the email announcement

The following command uses the build-aux/announce-gen script found in the gnulib sources. By default, it will match only release artifacts named '${package-name}-${version}', e.g. 'guix-1.3.0.tar.gz'. Since Guix includes various other artifacts such as ISO and QCOW2 images, it is useful to modify the script with the following command:

$ sed -E 's/(my @tarballs = ).*/\1glob("*.[xlg]z *.qcow2 *.iso");/' \ -i ~/.local/bin/announce-gen

The script must run from the release sub-directory containing the release artifacts, like so:

$ cd release-X.Y.Z $ announce-gen –release-type=stable –package-name=guix \ –previous-version=X1.Y1.Z1 –current-version=X.Y.Z \ –gpg-key-id=MY-KEY –url-directory=https://ftp.gnu.org/gnu/guix \ –news=../NEWS

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

Below the initial "About" section boilerplate that describes Guix should come the output of announce-gen, which should include the NEWS content for the release.

Send the email announcement

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

Post a news item on the web site (automated)

The blog post will automatically end up on planet.gnu.org and Planet Scheme.

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.

8.8 KiB Raw Blame History Unescape Escape