Subject: Re: bug#78332: [PATCH 1/1] 005-regular-releases: Initial draft of GCD005 'Regular and efficient releases'.

From: Steve George <[email-masked]>
Date: Sun, 22 Jun 2025 16:04:18 +0100

Hi Olivier,

On Wed, Jun 18, 2025 at 04:52:42AM +0000, Olivier Rojon wrote:
> Hi Steve, hi everyone,
> 
> first things first, thank you so much for your efforts for the Guix project.  Your awesome
> newbie-friendly blog posts, the Guix User and Contributor Survey, this GCD - thanks!
(...)

You're welcome :-)

> I have some comments to make (see below), but from my point of view, none of them HAVE to
> lead to changes in the GCD, because especially considering the proposed iterative nature
> of the process, many things will turn up during the first (or second, or third, ...)
> iteration that will lead to changes.  Overall, I think that this GCD proposes a
> much-needed structure to a frighteningly complex process that too often is stemmed by too
> few people.  I think most of its parts are actionable as is, and I really appreciate that
> you took so much time to investigate how other distributions do it and that you spelt out
> a road map that the release team can use to guide their actions.  I am certain that I
> would be lost without such guidance, and I do appreciate that leeway for unpopular "behind
> the scenes" work such as ungrafting is taken into consideration.
> 
>

Thanks for going through it in detail and both the wider thoughts and specific points really help.

> Package Sets
> ============
> I have to admit to a certain brain tangle when it comes to this topic and I read many
> contributions to the discussion to go towards this direction.  If I understood the
> discussion correctly, the first release process is likely to feature Guix veterans.
> Wouldn't it be possible to deliberately underspecify which package sets (how many) are
> present and what their contents are?  This could take two different forms: one would say
> that the release team can decide what to feature provided they test it according to the
> outlined criteria (for all architectures etc), the other would say that the first release
> team (comprised of veterans) lays the ground work and future release teams might have some
> wiggle room.
(...) 

Thanks for going through it. Overall, I think you're right and actually I should not have tried to "specify" them. 

I agree that what's going to happen is that each successive Release Team has to figure out what should be "added" (if anything), but you can't really remove too much stuff because users come to rely on things. I've just tried to realign the whole section on the basis of the current system, and to clearly word the intent - which is all about the focus of QA/manual testing.

> release cycle start in $SPRING
> ==============================
> for me personally the Guix Days were a catalyst and were motivating me to get involved
> more concretely in the project than beforehand.  Maybe the end of Guix Days/FOSDEM could
> be mentioned as a concrete starting point because then, a possible release team has
> (possibly) had time to coordinate in person what awaits them in the following weeks.  And
> if it hadn't had time, (possible) members of the release team have had ample opportunity
> to charge their social and geek batteries and might be willing and able to release it ;-)

That's a great idea, and in fact we did discuss at Guix Days so it makes sense.

I'm feel the GCD is too long already, but I think you're absolutely right about this - I've changed the Appendix 1 flow.

> iterative process improvements/Release Cheat Sheet
> ==================================================
> I think it is a very important step in the iterative process of release management that
> lessons learnt make future iterations easier.  The discussion has often times mentioned
> automation, the GCD mentions the "communication afterwards, possibly with a blog post".
> My supplementary idea is to write up a kind of "TODO List" or a "Release Cheat Sheet" (or
> whatever you want to call it) that mentions either (a) all the steps required from start
> to finish (that's what helps me with complex tasks where I need to be vigilant with each
> step so I don't want to think about the overall structure, or (b) the typical GOTCHAS,
> things that you forgot that really came back to bite you. 

Yes agreed, we'll get better if we "do" releases more often, and "document" what we learn.

The Appendix 1 plan says that each Release Team will do a Release Retrospective which is supposed to capture how to improve the overall release process. 

Specifically for documentation I had in mind the Ubuntu or NixOS release wiki docs https://nixos.github.io/release-wiki/Home.html.

We already have some as a starting points - https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/release.org
 
I think your (a) is basically covered in a detailed version of the Appendix 1 plan, and then (b) is going to be added to the release documentation over time (as we discover those gotchas!) 

> motivation for release: sync codebase and documentation
> =======================================================
> I don't know if that has already been mentioned, but another reason why a release can be
> good is to have a kind of synchronisation between what the distro can do and what is
> documented (where).  The current state of affairs is to make sure to always use the devel
> version of the manual which I think is a terrible way to introduce newbies, while the 1.4
> version -- the "correct" manual for the installer you download and install -- features
> quite some dead links etc. while being so out of date in places that we might as well --
> I'm exaggerating to make a point -- replace it with a fantasy novel.
> 

Agreed, I think we see this a lot on IRC - users read the wrong version and are confused!

The GCD reflects this at the start:

1. New installations of Guix will be better because installation media and
   manuals will be up to date.

It's right at the start, but you didn't internalise it - should it be drawn out more? (bearing in mind I'm also fearing the length at this point!)

> META: structure of the document
> ===============================
> Would it make sense to make the sections "Package Sets", "Plattforms and Architecture tiers", "Release artifacts" and "Release team and project" top level headings?  The way I read it they appear as aspects of the whole GCD while not standing in a content dependency relation to the "Motivation" section.
> 

Yeah OK, everything you say makes sense in this bit.

As the documents becoming far too long ... I've added more words!!!

I've added a "conclusion" at the start to show what three of these things are about (reducing scope) and then made those three things (package sets, architectures and release artifacts) sub-sections. I've moved Release team up a level as well.

> The same applies to the Appendix section, where I'd argue that when the Appendix is a
> top-level heading and the explanation of the different "Events" are its direct children,
> it would make sense to have their explanation on level 2 and not level 3.
(...)

Thank-you, fixed.

> @text: Package Set Finalisation
> =========================
> I don't understand the following sentence:
> 
> > 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.
> 
> The sentence would be fine without the part "so could be risk of removal".  This part of
> the sentence (to me) alludes to another aspect -- "risk of removal" -- that remains
> underspecified and thus causes confusion.  Unless it is a mistake, I think it would be a
> good idea to rephrase to make the two aspects "deprecation of packages that don't build on
> the primary architecture" and "risk of removal" clearer.
(...)

It's my understanding that the topic of package removal has caused lots of discussion previously. There's already a Deprecation Policy in place which specifically covers both the circumstances and timing of removal. I didn't want to cover that ground again, as I don't want to relitigate it! So I've said that the Release Team can make some decisions early and then there's time for a big discussion and decisions. Consequently, I'm being diplomatic here and it's intentional :-)

> @text: Toolchain and transition freeze
> ======================================
> Maybe a criterion such as with package updates could be used here, like "if a change in
> package X incurs change in Y (say, 50) other packages, it needs to be treated specially".
> 
(...)

Yeah, I personally don't think I can clarify it. It would need someone with more direct release experience. 

Thanks so much!

Steve / Futurile