[bug#78332,1/1] 005-regular-releases: Initial draft of GCD005 'Regular and efficient releases'.
Commit Message
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!
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.
=================================================================
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.
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 ;-)
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.
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.
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.
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.
@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.
@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".
=================================================================
I also append a patch file. Here I applied some (or all? dunno) the proposed "structure
of the document" and made some minor edits that I came across while reviewing the
document.
Again, thank you so much for your contribution, Steve! :)
Have a good day everyone,
Olivier
Steve George <steve@futurile.net> writes:
> Hi all,
>
> Thanks for all the feedback on the initial proposal.
>
> I've integrated it into the GCD so attached is a revised version. I think it's ready to move to the Discussion Period (minimum 30 days from today).
>
> A short summary of the changes in this version:
>
> - Rename staging to integration branch with suggestion of next-master [Zheng Junjie]
> - Add benefit of updated distribution through other package managers [Rutherther]
> - Remove reference to faster initial git pull [Rutherther]
> - Move target annual release to June [Rutherther]
> - Reduce freeze period by breaking it up into stages [Rutherther & others]
> - updates freeze (week 8->12), hard freeze (week 10-12)
> - Identify pacakge sets earlier [Vagrant]
> - Reword template plan to show weeks [Vagrant]
> - Add alternative release target weeks to plan [Vagrant]
> - Identify 'at risk' packages earlier [Greg / Andreas]
> - Make automation a goal of the Release process & release team [Greg / Ekaitz / reza]
> - Reduce the scope of package sets [Jelle / Efraim]
> - Provide more clarity on dealing issues in package sets [Rurtherther]
> - Try to clarify options around RC bugs and package build failures
> - Try to clarify purpose of release project plan as a template
>
> I would love to know if this improves things from any feedback that you gave?
>
> As well as any other thoughts, comments or ideas on how to improve this GCD!
>
> Steve / Futurile
@@ -106,7 +106,7 @@
the **November of 2025**, with a short cycle to release in June 2026.
-## Package Sets
+# 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.
@@ -157,7 +157,7 @@
Linux kernel could block a release, but not an issue in a game.
-## Platforms and Architecture tiers
+# 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
@@ -194,7 +194,7 @@
a release would be removed from the archive using Guix's deprecation policy.
-## Release artifacts
+# Release artifacts
Using the primary architecture tier and the package sets would involve creating
the following release artifacts:
@@ -208,7 +208,7 @@
not block a release.
-## Release team and project
+# 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
@@ -291,11 +291,9 @@
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.
+(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 adding an additional slower release cadence.
@@ -335,21 +333,21 @@
| +2 | Release retrospective |
| +2 | Relax - it's done! |
-### Nominate a release team (week -5)
+## Nominate a release team (week -5)
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.
-### Notify teams of upcoming release (week -4)
+## 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)
+## Release project start (week 01)
Start the project with weekly updates to guix-dev and regular meetings of the
release team. Encourage participation in testing and identifying bugs from
the community.
-### Package set finalisation (week 03)
+## 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.
@@ -357,7 +355,7 @@
removal will be identified and developers will be notified following the
Deprecation Policy.
-### Toolchain and transition freeze (week 04)
+## 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.
@@ -370,7 +368,7 @@
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)
+## Initial testing (week 06)
An initial testing sprint to look at packages, services, install media and
upgrade testing. This should identify:
@@ -388,7 +386,7 @@
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 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'**.
@@ -397,7 +395,7 @@
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)
+## 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.
@@ -408,15 +406,15 @@
staging branch while they do release stabilisation to prevent big flows of
breaking changes into master which broke one of their releases [^7].
-### Ungraft master branch (week 08)
+## 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)
+## 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)
+## Branch and tag release branch (week 09)
The master branch is tagged and a new release branch is created.
* master branch: security only.
@@ -426,7 +424,7 @@
changes stay in a team branch or go to an integration branch. The focus on the
release branch is to stabilise so only resolutions to bugs should be pushed.
-### Testing and Hard Freeze (week 10)
+## 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
@@ -438,13 +436,13 @@
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 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.
-### Final release target (week 12)
+## Final release target (week 12)
Final release is targeted for this date. All planning and work should be done
to this date.
@@ -455,7 +453,7 @@
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)
+## 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.
@@ -464,7 +462,7 @@
workarounds at this date they may move the release to Alternative release
target #2.
-### Alternative release target #2 (week 16)
+## 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.
@@ -473,17 +471,17 @@
without workarounds they may move the release to an alternative date or cancel
the release.
-### Integration branch merged to master (release +1 week)
+## 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)
+## 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)
+## 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