Regular and efficient releases

by Steve George — Fri 09 May 2025
sponsored by Andreas Enge, Ludovic Courtès, Efraim Flashner

Timeline

09 May
drafting21 May
discussion23 June
deliberation07 July
deliberation closed

Summary

Guix doesn't have a regular release cycle which has led to infrequent new releases. Sporadic releases are detrimental for our users, contributors and the project. This GCD proposes we implement an annual release cadence and simplify the release process to make releases easier.

The project currently releases new versions of Guix on an ad hoc frequency. The 1.4.0 release happened in December 2022 ^1, which is almost 2.5 years ago, at the time of writing.

The weaknesses in this release strategy are:

1. No clarity on when the next Guix release is.
2. Releases are complex and toil for developers.
3. Rolling updates aren't suitable for all users.

This GCD proposes the following combined solution for solving the challenges associated with #1. and #2. above:

1. Regular releases: switch to a time-based release of Guix every year.
2. Efficient releases: use package sets and supported architectures to reduce the scope of work required to create a Guix release. Create a rotating Release Team who will organise each release, with the goal of automating releases wherever possible.

The benefits will be:

1. New installations of Guix will be better because installation media and manuals will be up to date. The version of Guix distributed through other GNU/Linux distributions will also be more recent.
2. Package installation will improve for all users. Packages will be ungrafted during each release cycle.
3. Package quality will improve for all users, because regular releases will provide a cadence for focusing on our quality.
4. A regular cadence for promoting the project to potential users. Helping us to inform more people about the benefits of using GNU Guix!
5. A regular release cycle is a rallying point for our contributors giving them a consistent calendar of when to focus on releases versus other hacking.

This GCD doesn't attempt to address the challenge that rolling updates aren't suitable for all users (#3. above). Adding a slower-moving branch akin to Nix's stable could be an eventual goal [^2]. However, this GCD aims for a single achievable change by implementing regular releases which is a substantial change that would be a big improvement for our users.

Motivation

Releases are important for any Free Software project because they update the user experience and are a focal point for excitement [^3]. Regular releases help us to improve the quality of our software by bringing focus, and exercising regular usage scenarios (e.g. testing the installer).

The majority of distributions follow time-based releases, six months is a common cycle time. For further comparison see the research on the release strategies of distributions . A summary is:

• NixOS: releases every six months (May/November), both rolling release and slower stable branch.
• OpenSUSE: rolling release, slow-roll release and fixed releases.
• Ubuntu: every six months, with 9 months maintenance. LTS releases every 2 years.
• Debian: Every 2 years (not time fixed), with about 4-5 months of package updates freeze before the release while bugs are ironed out.

As a rolling release Guix immediately provides the latest improvements to users. Consequently, it could be argued that releases are unnecessary. However, they provide a focal point for the project to undertake additional testing and stabilisation across the repository. They also ensure we update installation media, documentation, themes and web site.

A specific issue caused by irregular releases is that new users/installs may have a poor initial user experience due to time-bombs which occur in obsolete packages and their test suites. People installing from a release tarball often find that important packages fail to build, making their initial attempts to use Guix unnecessarily hard. Old release artifacts also risk upstream sources disappearing and require the project to keep older substitutes on our servers.

People using Guix installed on another GNU/Linux distribution often use the guix-daemon packaged by their distribution. This means that any daemon related changes, such as a change to substitute's compression algorithm or changing the substitute servers, only reach those users after their distributions have updated their packaged guix-daemon version. Downstream GNU/Linux distributions will only package new official releases from the project.

Regular releases are also good for casual users because they provide an opportunity for us to promote new features and improvements. For prospective users promotional activity about the release means they are more likely to hear about capabilities that will attract them to experiment with Guix.

Many desktop distributions release every six months to align with the major desktop environments (GNOME/KDE) who release two or three times a year. This is why Nix (May/November) and Ubuntu (April/October) align their releases.

Since Guix is used extensively as a desktop it would make sense to align with these upstream releases. However, given that Guix is a volunteer project that doesn't have the practise of releasing it's unrealistic to move to two releases a year. Something along these lines could be a future goal [^4].

This GCD proposes an annual release cycle, with releases in June.

To move onto this cycle the first release would be a little later: aiming for the November of 2025, with a short cycle to release in June 2026.

Creating efficient releases

To create efficient releases we need to focus efforts by defining the scope of work that the Release Team does.

The result of the interaction between package sets, architectures and release artifacts is that the Release Team's QA and testing is reduced as follows:

1. Packages and services within the package sets must build on the primary architectures. Other packages are optional for a release.
2. Release artifacts are only made from packages within the package sets and on the primary architectures. Other architectures or release artifacts are optional for a release.
3. Testing and QA is on package sets on the primary architectures only. The Release Team has flexibility to choose their response to bugs and issues.
4. Testing is prioritied towards the installation of Guix System and Guix (on a foreign distribution) using the release artifacts. Practically, this means testing Guix System installs using the ISO image and QCOW2 image; and that Guix installs on a foreign distribution using the binary installer.
5. Each successive Release Team will look for ways to automate releases which may enable more efficient releases and alterations in the scope.

Package Sets

There are currently over 30,000 packages in the archive, it's unrealistic for all packages to receive the same amount of QA effort for a release.

Many other distributions focus attention on the critical parts of their repository by identifying those packages that are required for a particular use-case. For example, Arch Linux limits their efforts to a specific repository (called "main"). Ubuntu identifies various seeds for specific use-cases which determines their maintained packages; other packages outside these sets do not receive security updates.

Guix is both a package manager that can be hosted on other GNU/Linux distributions, and a GNU/Linux distribution itself. Limiting the range of packages and services that receive attention is consequently more complicated. Guix already has manifests to track which packages are used by Guix System's installer , so this proposal extends that concept.

For this proposal each successive Release Team would identify key packages which would receive the most Quality Assurance (QA) attention in that release.

The package sets would be:

• Required packages: packages required to boot and install a minimal Guix System or install Guix on a foreign distribution. This only includes default options required by the installer which must work for a release since they are part of the default installer path. For example, this would include the guix daemon, kernels, boot loaders, file-systems and minimal utilities.
• Desktop packages: additional desktop environments and other options from the installer. This includes packages that are part of the installer (but not default) and other popular options as chosen by the Release Team. Packages should work, but they may receive less QA attention from the Release Team than %system_packages.
• Important packages: important packages that anyone may wish to install on Guix and consequently the project wants to maintain substitutes for. This may include important toolchains, runtimes and utilities. The Release Team may perform QA on these packages.

Guix would still make all packages and services part of a release (the entire archive). Guix teams would be asked to test the parts of the archive that they look after. But, only Release Critical bugs in the package sets could block a release.

The Release Team may identify other package sets as needed.

Packages within the packages sets must build on the primary architectures (see definition lower). As part of the release's QA contributors would be asked to test these packages.

Where a significant issue is found within a package or service that's part of a package set the Release Team would work to resolve the problem. This could involve (but isn't limited to) fixing the underlying issue, documenting it as a limitation in the release notes or promoting an alternative and deprecating the broken package using the Deprecation Policy. As always, packages may be un-deprecated and returned to the archive at a later date.

Given the constraints on developers the overal aim of the package sets would be for them to be as small a set of packages and services as reasonably possible. It would mean that developers could focus on the critical packages and services during a release. As an example, this would mean that a major issue in the Linux kernel could block a release, but not an issue in a game.

Platforms and Architecture tiers

Guix is built and maintained on multiple different architectures, and two kernels (Linux, GNU Hurd). As the goal of the project is to maximise user freedom this variety is significant and is a key motivator for developers.

However, with limited resources (developer and CI) we want to make it as efficient as possible to create a release. The more toil involved in a release the less likely developers are to work on it.

The 2025 Guix User Survey showed that 98% of users were on x86_64 and 19% on AArch64. Consequently, the proposal is the following tiers:

• Primary architectures:

  • Architectures: x86_64, AArch64
  • Kernel: Linux
  • Coverage: all packages and services that are not explicitly platform specific must work to be included in the archive.
  • Package status: package updates should build for this architecture. If a package update is broken it must not be pushed to users (e.g. master).

• Alternative architectures

  • Architectures: all others
  • Kernel: Linux, Hurd
  • Coverage: all packages and services that are not explicitly platform specific may build
  • Package status: package updates should work for this architecture. Updates that do not build for this architecure, but do build for a primary architecture may be pushed to users.

Packages or services that do not build for the Primary architectures as part of a release would be removed from the archive using Guix's deprecation policy.

Release artifacts

Using the primary architecture tier and the package sets would involve creating the following release artifacts:

• GNU Guix System ISO image
• GNU Guix System QCOW2 image
• GNU Guix binary installer
• GNU Guix source tarball (as produced by make dist)

The Release Team should co-ordinate with any downstream GNU/Linux distributions that packages Guix to assist them to make the new release part of their distribution.

Again in an effort to reduce developer toil, additional release artifacts could be created but would not be part of the formal release testing and errors would not block a release.

Release team and project

A regular release cycle should galvanise all Guix developers to work on our releases. But, to ensure there are sufficient people involved a call will be put out to create a specific release team for each release project. We would expect the final release team to be around four-six members. The release team will work together to fix issues and test the various release artifacts. The expectation is that the release projects will be as short as possible, around a 12 week commitment with each team member having a few hours a week to take part.

The project would like to achieve releases with the minimum amount of effort by developers. Consequently, a goal for each Release Team is to find ways to automate releases reducing the toil of successive releases.

To manage the release it's proposed that each release will have a Release Manager role. The role of the Release Manager is to:

• co-ordinate the release project
• communicate with the release team and wider developers status and release critical bugs
• arbitrate changes to release blocking bugs, package sets and release artifacts
• influence and assist teams to resolve problems
• define the release artifacts and create them
• encourage and excite everyone to create and test the release

The Release Manager role is likely to require the most effort, so it will be rotated and consist of two people from the release team. For each release there would be a primary person and a secondary person in the role. The primary person is new to the role. The secondary person has previously done it and is mentoring the new person. The impact of this is that each new release manager is agreeing to take responsibility during two release cycles. This system is modelled on the Nix release management approach.

One of the release team will take on the role of Release Advocate [^5]. They will take responsibility for preparing the release announcement and coordinating the creation of content to promote the new release (e.g. web site) This role can be done by any member of the Guix community who has sufficient interest.

The final release team is:

• a new Release Manager
• a returning Release Manager
• up to 4 other members, one of whom acts as the Release Advocate

The Release Managers of each release will create and communicate a release project plan setting out the stages and dates for each stage. To try and galvanise the Guix development team to focus on the release it's envisioned that a release project will be about 12 weeks. See Appendix 1: Release Project Template for an example.

In order to improve knowledge transfer and reduce the toil of doing releases the Release Managers for a release will document the release process. There is inspiration for this in NixOS's release wiki and we already have detailed release documentation .

Cost of Reverting

If regular releases were not successful then the project would switch back to irregular releases. There would be no impact for exiting users as they will be tracking the rolling release's master branch.

If the project is able to successfully undertake regular releases then over time it may be possible to undertake full releases every six months or some other release cadence.

Drawbacks and open issues

There's no particular drawback to attempting regular release. It should be noted that the project is entirely dependent on volunteers so it may be that contributors don't have enough time available to achieve regular releases. If that's the case we would revert back to irregular releases.

Appendix 1: Release Project Template sets out a proposed time-line and major steps to be undertaken by the project to release a new version of Guix. It proposes freezing master while the team focuses on releasing the new version of Guix. Specifically, a major updates freeze (week 8->12), and a hard freeze (week 10->12). The drawback of this approach is that it would slow the velocity of changes. During this period contributors would have to keep updates on team branches, or use an alternative temporary branch. Each Release Team will iterate and improve the release process, so it's possible that this freeze period will be reduced, changed, or removed over successive releases.

There are various improvements that could be made to the release strategy over time, such as:

1. Create separate releases of the Guix source necessary for installing Guix on a foreign distribution. This would mean that downstream GNU/Linux distributions that package Guix could have new release more often.
2. Adding an additional slower release cadence. This could be either a security and critical fixes branch strategy, such as implemented by Nix. Or it could be a slightly slower moving branch, such as implemented by SUSE SlowRoll [^4].

Appendix 1: Release Project Template

To show the major steps of a release this release project template is a starting point. After each successive release the Release Team will undertake a retrospective and will document improvements that can be made to the release process and areas to automate to improve efficiency.

The aim in this template is for a 12 week active release project, with the first one using 16 weeks in total to give teams time to prepare.

The current outline builds from our current release document

Nominate a release team annually

Nominate a release team with two Release Managers (1 is the previous RM), and up to 4 other people who will work on the release. Put out a call for a Release Advocate who can be anyone in the Guix community who's willing. The best time to do this would be annually at Guix Days as it's a natural motivational point in the calendar.

Notify teams of upcoming release (week -4)

Make sure all teams are aware of the upcoming release. This gives them 4 weeks to undertake any large transitions or major changes.

Release project start (week 01)

Start the project with weekly updates to guix-devel and regular meetings of the release team. Encourage participation in testing and identifying bugs from the community.

Package set finalisation (week 03)

Specify the package sets for this release. The Release Team will identify all packages and their inputs so that a full manifest for the release is created.

Packages that do not build for the primary architectures so could be risk of removal will be identified and developers will be notified following the Deprecation Policy.

Toolchain and transition freeze (week 04)

No major changes to toolchains (e.g. gcc-toolchain, rust-1.xx) or runtimes (e.g. java). There should be no changes that will cause major transitions.

Debian defines a transition as one where a change in one package causes changes in another, the most common being a library. This isn't suitable for Guix since any change in an input causes a change in another package. Nonetheless, any change that alters a significant number of packages should be carefully considered and updates that cause other packages to break should be rejected.

No alterations to the Guix daemon are accepted after this point. Packages and services in the 'minimal' package set should not be altered.

Initial testing (week 06)

An initial testing sprint to look at packages, services, install media and upgrade testing. This should identify:

• packages or services that may need to be removed because they fail on a primary architecture
• packages and services in the package sets install and can be used
• installation artifacts can be created and used
• example system definitions can be used
• system upgrades

Update the list of packages that's at risk of being deprecated following their identification in `Package set finalisation: see if these build failures have been resolved.

A build failure of a package or service that's in a package set will be marked as a blocker for the release: Release Team to make determination on response.

Major updates freeze (week 08)

Major package updates are frozen on 'master' as the focus is on fixing any blocking packages. Security updates still go to 'master'.

All major changes not related to the release remain on team-branches.

Team branches can still be folded into the release branch as long as changes are minor package upgrades.

Breaking changes to an integration branch (week 08)

If there are major breaking changes that must be moved from a team branch an integration branch will be created. For example next-master, this will be short-lived, existing only until after the release.

The master branch slows down from this week until the release.

This concept comes from the Nix project where they flow big changes into a staging branch while they do release stabilisation to prevent big flows of breaking changes into master which broke one of their releases ^6.

Ungraft master branch (week 08)

Guix master is ungrafted to minimise the difference with users of the release initial 'guix pull' experience.

Bugs and documentation focus (week 09)

The master branch should be quiet at this point as everyone should focus on testing and resolving any bugs. New documentation can also be done.

Branch and tag release branch (week 09)

The master branch is tagged and a new release branch is created.

• release branch: regularly merged from master, tracks the release artifacts.
• master branch: receives security and resolutions of RC bugs.
• next-master: everything that normally goes to master.

At this point in time the master branch only receives security updates and resolutions of RC bugs. The focus is on stabilising, creating release artifacts and ensuring that the substitute builders have caught up. The release branch receives regular merges from the master branch: the release artifacts are built from this branch, so it tracks the release. All other changes stay in a team branch or go to an integration branch (e.g. next-master).

Only security updates go to the master branch from this point. All other changes stay in a team branch or go to an integration branch (e.g. next-master). The focus on the release branch is to stabilise so only resolutions to bugs and anything required to create release artifacts should be pushed.

Testing and Hard Freeze (week 10)

Release Crictical (RC) bugs and issues should be solved for the release branch.

Only changes that will fix a non-building package, or a RC bug in a package/service are allowed. Ideally avoid new upstream versions, but it's acceptable to use a new minor upstream version to solve a bug.

Any non-building packages are deprecated using the Deprecation Policy. As always, packages can be un-deprecated at a later date.

The drawback of a freeze is that it slows down changes reaching users. As each Release Team iterates and improves the release process they will consider whether this freeze period can be reduced, changed, or removed.

Call for testing from all developers and users: goal is to test the main installation use-cases and packages within the package sets.

Release candidate (week 10)

Release artifacts are created for the release candidate. There's a final 2 weeks of testing with these artifacts. If there are no release blocking bugs discovered then the release uses these artifacts. If bugs are found/fixed then release artifacts are regenerated as needed.

Prepare release communications (week 10)

Determine all the changes of interest and highlights that will be communicated to users during the release. At a mimimum this will be an update to the NEWS file, and a blog post.

Final release target (week 12)

Final release is targeted for this date. All planning and work should be done to this date.

The new release is announced and new release artifacts are published.

If the Release Team determines that release has Release Critical bugs without workarounds they may move the release to Alternative release target #2. The concept of buffer weeks to ensure the release balances time and quality comes from Fedora's release plan

Alternative release target #1 (week 14)

This release target date may be used if the Release Team determines that there were Release Critical bugs without workarounds at the Final release target date.

If the Release Team determines that release has Release Critical bugs without workarounds at this date they may move the release to Alternative release target #2.

Alternative release target #2 (week 16)

This release target date may be used if the Release Team determines that there are Release Critical bugs without workarounds at one of the previous target dates.

If the Release Team determines that the release has Release Critical bugs without workarounds they may move the release to an alternative date or cancel the release.

Integration branch merged to master (release +1 week)

If there were any breaking changes placed onto the integration branch (e.g. next-master) then these can be merged into the master branch at this point. The master branch then continues as normal.

Release retrospective (release +2 weeks)

A retrospective is undertaken by the release team to understand how the release process can be improved to make it more reliable for users and easier/efficient for developers.

Relax! (release +2 weeks)

The release has been cut, everyone is now excited, and hopefully all is well. Take some time off from release work! There's some time built-in here to relax and get back to other hacking before it's time to start again with the next release.

[^2]: Examples of distributions that have cadences for different users and screnarios are Nix's stable branch, OpenSUSE's SlowRoll branch and Ubuntu's LTS (Long Term Support) releases.

[^3]: the aspect of creating news and excitement for casual users is well-known in the FOSS community. An example from GNOME's earlier days.

[^4]: OpenSuse has a SlowRoll branch where they release a smaller set of package updates on a monthly basis. This is an interesting innovation as it allows users to still benefit from a rolling release but at a slower rate of change (fewer regressions). They are also not dropping too far behind the rolling release, so there's not as much maintenance for OpenSUSE developers dealing with an out of date release branch and having to backport software.

[^5]: Nix has the concept of a Release Editor who is responsible for improving the legibility of the release notes. Our version extends the idea to make sure other artifacts and activities that promote the release happen.