* doc/release.org: Update it.
8.8 KiB
Release Process for GNU Guix
- Update NEWS
- Prepare & upload tarball
- Create branch 'version-X.Y.Z'
- Enter a guix environment containing everything needed
- Bootstrap and build
- Add a Git tag
- Update the translation files
- Run “make release” for one or several release candidates
- Push the branch
- Merge the version-X-Y-Z branch into master
- Upload all the files
- Add a Cuirass jobset for branch 'version-X.Y.Z'
- 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 shell imagemagick perl -D guix
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/76078782392fe9826a6a47537ee9b85910fd96c9/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.
Copyright © 2014, 2018, 2019 Ludovic Courtès <ludo@gnu.org> Copyright © 2021 Maxim Cournoyer <maxim.cournoyer@gmail.com> Copyright © 2011, 2012, 2013 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.