Hi all,
After a good long discussion I'm moving GCD005 to Deliberation.
The final version is below and can be found on Codeberg:
https://codeberg.org/guix/guix-consensus-documents/src/branch/main/005-regular-releases.md
This means that team members have 14 days to send one of the following replies
on the patch-tracking entry of the GCD:
- “I support”, meaning that one supports the proposal;
- “I accept”, meaning that one consents to the implementation of the proposal;
- “I disapprove”, meaning that one opposes the implementation of the proposal.
The Issue is:
78...@debbugs.gnu.org
https://issues.guix.gnu.org/78332
In terms of next steps beyond the GCD, Efraim has said he's willing to be the
next Release Manager, and both myself and Andreas have committed to help out -
I'm sure there will be others!
Thanks so much!
Steve / Futurile
title: Regular and efficient releases
id: 005
status: submitted
discussion: https://issues.guix.gnu.org/78332
authors: Steve George
sponsors: Andreas Enge, Ludovic Courtès, Efraim Flashner
date-submitted: 2025-05-21
SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
---
# 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](https://codeberg.org/futurile/guix-org/src/branch/master/release-mgmt)
. 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](https://guix.gnu.org/en/blog/2025/guix-user-and-contributor-survey-2024-the-results-part-1/)
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](https://git.savannah.gnu.org/cgit/guix.git/tree/etc/manifests/release.scm)
, 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](https://guix.gnu.org/en/blog/2025/guix-user-and-contributor-survey-2024-the-results-part-2/)
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](https://codeberg.org/futurile/guix-org/src/branch/master/release-mgmt/nix-release-mgmt.md)
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](https://nixos.github.io/release-wiki/Home.html)
and we already have detailed [release documentation](https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/release.org)
.
# 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](https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/release.org)
| Week of Project | Event |
| --- | --- |
| N/A | Nominate a release team |
| -4 | Notify teams of upcoming release |
| 01 | Release project start |
| 03 | Package set finalisation |
| 04 | Toolchain and transition freeze |
| 06 | Initial testing |
| 08 | Major updates freeze |
| 08 | Breaking changes to next-master |
| 08 | Ungraft master branch |
| 09 | Bugs and documentation focus |
| 09 | Branch and tag release branch |
| 10 | Testing and hard freeze |
| 10 | Release candidate |
| 10 | Prepare release communications |
| 12 | Final release target |
| 14 | Alternative release target #1 |
| 16 | Alternative release target #2 |
| +1 | Integration branch merged to master |
| +2 | Release retrospective |
| +2 | Relax - it's done! |
## 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](https://docs.fedoraproject.org/en-US/releases/lifecycle/#_release_dates)
## 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.
---
[^1]: https://guix.gnu.org/en/blog/2022/gnu-guix-1.4.0-released/
[^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](https://mail.gnome.org/archives/gnome-hackers/2002-June/msg00041.html).
[^4]: OpenSuse has a [SlowRoll branch](https://en.opensuse.org/Portal:Slowroll)
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](https://nixos.github.io/release-wiki/Release-Editors.html)
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.
[^6]: https://github.com/NixOS/rfcs/blob/master/rfcs/0085-nixos-release-stablization.md
