Subject: Re: GCD005: Regular and efficient releases

From: Vagrant Cascadian <[email-masked]>
Date: Fri, 09 May 2025 12:48:32 -0700

On 2025-05-09, Steve George wrote:
> It's been ~2.5 years since the last Guix release, which led me to
> think we should do another one! Initially, I was just going to see if
> anyone wanted to create a release project. But, before I knew it I was
> writing a GCD! ...

Thanks for nudging this forward! :)

> # Summary
>
> Guix doesn't have 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:
>
> 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.
>
> The benefits will be:
>
> 1. New installations of Guix will be better because installation media and
>    manuals will be up to date, and the initial 'guix pull' will be faster.
> 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.
>
> Adding a slower-moving branch akin to Nix's stable could be an eventual goal as
> it would increase Guix's suitability for some users and use-cases [^2].  However,
> this GCD only sets out to implement 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:
...
> - Debian: Every 2 years (not time fixed), with about six months of package
> updates freeze before the release while bugs are ironed out.

Maybe more like 4 or 5 months, but who's counting? :)

Notably, Debian has time based freezes, and releases "quando paratus
est" ... e.g. when it is ready (e.g. no major blockers to release).

I think this is a more realistic and honest model for a volunteer
project than trying to make a time-based "release", as you can predict
or decree when you are going to start the process, but you cannot
reliably predict when you will finish.

> 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.
...
> This GCD proposes an annual release cycle, with releases **in May**.
>
> 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 May 2026.

For what it is worth, May would be awful timing for getting guix into
Debian stable releases, which tend to approach a hard freeze around that
time of year, so Debian stable will always end up effectively (at least)
one release behind... but you cannot please everybody. :/

A yearly release cycle would at least allow Debian to provide backports
of guix more reliably, at least...

Of course, we are about to see the second Debian release since the
release of guix 1.4.0, so this proposal would still be a huge
improvement!

> ## Package Sets
...
> Guix is both a package manager that can be hosted on other Linux distributions,
> and a Linux distribution.  Limiting the range of packages 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 Guix would identify key package sets which would receive the
> most attention for QA'ing a release.
>
> The package sets would be:
>
> * minimal: packages required to boot and install a minimal Guix or Guix System
> install.  This would include the guix daemon, kernels, boot loaders,
> file-systems and minimal utilities.

This seems a reasonable broad-strokes starting point, nice!

> * standard: packages that create a core installation for all other
> uses.

I fail to see a distinction between minimal and standard, perhaps due to
"core installation", so this perhaps could use a bit more elaboration.

> * desktop: provides the packages necessary for a desktop.  This would include
> things like X11/Wayland, desktop environments, key applications and themes.

It seems like all desktop environments is awfully broad, as there are
some unusual or niche desktop environments in Guix, although Guix users
maybe also tend to fill certain niches more than the general
population. Still, I suspect this should maybe be narrowed down to a
more specific set...

> * server: provides packages and services for a server.  This would include
> standard server packages and services.

What are "standard server packages and services" ?

> * hosted: provides packages and services which are necessary in hosted usage.

What are these?

> ## 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.
...
> - 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).
>   - Security: all packages that are maintained upstream receive updates
>
> - 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.
>   - Security: no commitment to providing security updates for this architecture.
>
> 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.

Sounds reasonable.

> ## 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 installer
>
> 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.

Do we currently have all these for x86_64-linux and aarch64-linux, the
two proposed primary architectures?

> # 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.
>
> There are various improvements that could be made to this process over time,
> but no known issues.

I think someone already mentioned freezing master should be noted as a
drawback. I would, in a weird way, second that, despite thinking it is
actually a feature. :)

> # Appendix 1: Release Project Time-line
>
> To illustrate the major steps of a release project this is a rough time-line.
> The aim is for a 12 week active release project, with the first one using 16
> weeks in total to give teams time to prepare.

Ambitious, but may as well aim high!

> 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 |
> | --- | --- |
> | -5 | Nominate a release team |
> | -4 | Notify teams of upcoming release |
> | 01 | Release project start |
> | 04 | Toolchain and transition freeze |
> | 05 | Package set finalisation |
> | 06 | Initial testing |
> | 08 | Updates freeze |
> | 08 | Breaking changes to staging |
> | 08 | Ungraft master branch |
> | 09 | Bugs and documentation focus |
> | 09 | Branch and tag release branch |
> | 09 | Testing and hard freeze |
> | 10 | Release candidate |
> | 12 | Final release |
> | 13 | Staging merged to master |
> | 14 | Release retrospective |
> | 15+| Relax - it's done! |

The weeks listed here are -5 indexed, but are described as a 1 indexed
bulleted list, it would be nice to keep them using the same indexing!

> ### 1. Nominate a release team
(a.k.a. ### -5.)

> ### 4. Toolchain and transition freeze
> 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.
...
> No alterations to the Guix daemon or modules are accepted after this point.
> Packages and services in the 'minimal' package set should not be altered.
>
> ### 5. Package set finalisation
> Specify the package sets for this release.  Identify all packages and their
> inputs so that a full manifest for the release is created.

It seems like you would need to clarify the toolchain package set the
week prior.

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

Yay! This should also give the build farms a chance to "catch up" with
builds.

> ### 8. Breaking changes to staging
> To avoid a period of time where teams can't commit breaking changes, these are
> sent to a new 'staging' branch, rather than directly to master.  The master
> branch slows down from this week.
...
> Team branches can still be folded into the release branch as long as changes are
> minor package upgrades.

If they are minor package upgrades, do you even need a team branch?

> ### 11. Branch and tag release branch
> The master branch is tagged and a new release branch is created.
>
> * master branch: security only.
> * release branch: security updates as normal. Only RC blocking bugs.
>
> Only security updates go to the master branch from week 9->13.  All other
> changes stay in a team branch or go to the `staging` branch. The focus on the
> release branch is to stabilise so only RC bugs should be pushed.

Spell out "RC" at least once in the document, presumably "Release
Critical"?

> ### 13. Release candidate
> Release artifacts are created for the release candidate.  There's a final 2
> weeks of testing with these artifacts.

Not sure how you cram two weeks into week 13! (or... is that week 10?)
:)

> If there are no release blocking bugs discovered then the releas uses
                                                         ^^ release ^^
> these artifacts.  If bugs are found/fixed then release artifacts are
> regenerated as needed.

As a downstream packager of Guix for Debian, I would appreciate
(pre)release candidates be included earlier in the process somehow.

Maybe even in sync with a weekly cadence in line with this release
process?

I usually do find bugs in the process of packaging Guix for Debian, and
it would be nice to more easily catch those earlier.

> ### 14. Final release
> Final release is announced and new release artifacts are published.

Yay!

Thanks again, really glad to see some good thoughts and energy go into
this!

live well,
  vagrant