Package: guix-patches;
Reported by: Noé Lopez <noe <at> xn--no-cja.eu>
Date: Sun, 8 Dec 2024 12:29:02 UTC
Severity: important
Tags: patch
Merged with 66844
Done: Noé Lopez <noe <at> xn--no-cja.eu>
Bug is archived. No further changes may be made.
View this message in rfc822 format
From: Simon Tournier <zimon.toutoune <at> gmail.com> To: 74736 <at> debbugs.gnu.org Subject: [bug#74736] [FWD] Guix Consensus Document process – deliberation Date: Wed, 22 Jan 2025 20:49:55 +0100
[Message part 1 (text/plain, inline)]
Repost because “550 This message scored 18.0 spam points.”
-------------------- Start of forwarded message --------------------
From: Simon Tournier <zimon.toutoune <at> gmail.com>
To: info-guix <at> gnu.org, 74736 <at> debbugs.gnu.org
Cc: [...]
all teams members
+ all people with commit access
Subject: Guix Consensus Document process – deliberation
Date: Wed, 22 Jan 2025 20:44:08 +0100
[Message part 2 (text/plain, inline)]
Hi all, Here is the Guix Consensus Document (GCD) process which implements how we will collectively make decision on *significant* changes. Since it bootstraps the process, it’s important to have a common understanding of it. If you are member of a team (etc/teams.scm), you are asked to send by email to 74736 <at> debbugs.gnu.org your reply, either: • I support; • I accept; • I disapprove. If you have commit access and not yet a member of any team, please consider to join one. Since we are bootstrapping the process, your reply matters too. :-) The Deliberation Period ends on February, 5th everywhere on Earth. Note that the Discussion Period is now done. Therefore, if you accept with strong concerns, please provide a summary (5-10 lines) that will be included in the final document. If someone disapproves, please explicitly point which major comment you did that had not been included in this final document. Attached the GCD file and the template file. Below various milestones if you need more context. Thanks for all the comments! I’m personally happy with this outcome. :-) Cheers, simon --
[001-gcd-process.md (text/markdown, inline)]
title: Guix Consensus Document Process
id: 001
status: submitted
discussion: https://issues.guix.gnu.org/74736
authors: Simon Tournier, Noé Lopez, Ludovic Courtès
sponsors: pukkamustard, Ricardo Wurmus
date: 2025-12-08
SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-only
---
# Summary
This document describes the _Guix Consensus Document_ (GCD) process of the
GNU Guix project, later referenced as either Guix or “the project“, for
brevity. The GCD process is intended to provide a consistent and
structured way to propose, discuss, and decide on major changes affecting
the project. It aims to draw the attention of community members on
important decisions, technical or not, and to give them a chance to weigh
in.
# Motivation
Day-to-day work on Guix revolves around informal interactions, peer review,
and consensus-based decision making. As the community grows, so does the
stream of proposed changes, and no single person is able to keep track of
all of them.
The GCD process is a mechanism to determine whether a proposed change is
*significant* enough to require attention from the community at large and
if so, to provide a documented way to bring about broad community
discussion and to collectively decide on the proposal.
A change may be deemed *significant* when it could only be reverted at a
high cost or, for technical changes, when it has the potential to disrupt
user scripts and programs or user workflows. Examples include:
- changing the `<package>` record type and/or its interfaces;
- adding or removing a `guix` sub-command;
- changing the channel mechanism;
- changing project governance policy such as teams, decision making, the
deprecation policy, or this very document;
- changing the contributor workflow and related infrastructure (mailing
lists, source code repository and forge, continuous integration, and so
on).
# Detailed Design
## When to Follow This Process
The GCD process applies only to *significant* changes, which include:
- changes that modify user-facing interfaces that may be relied on
(command-line interfaces, core Scheme interfaces);
- big restructuring of packages;
- hard to revert changes;
- significant project infrastructure or workflow changes;
- governance or changes to the way we collaborate.
Someone submitting a patch for any such change may be asked to submit an
GCD first.
Most day-to-day contributions do *not* require a GCD; examples include:
- adding or updating packages, removing outdated packages;
- fixing security issues and bugs in a way that does not change interfaces;
- updating the manual, updating translations;
- changing the configuration of systems part of project infrastructure in a
user-invisible way.
These day-to-day contributions remain governed by the process described in
the [”Contributing“ section of the GNU Guix Reference
Manual](https://guix.gnu.org/manual/devel/en/html_node/Contributing.html).
# How the Process Works
## Getting Started
1. Clone
https://git.savannah.gnu.org/git/guix/guix-consensus-documents.git
2. Copy `000-template.md` to `XYZ-short-name.md` where `short-name` is a
short descriptive name and `XYZ` is the sequence number.
3. Write your GCD following the template structure. The GCD must describe
a concrete idea and sketch a plan to implement it, even if not all
details are known; the GCD must not be a brainstorming session or a
vague idea but a concrete proposal. If it intends to deprecate a
previously-accepted GCD, it must explicitly say so.
4. Submit the GCD as a patch to `guix-patches <at> gnu.org`.
5. Announce your GCD at `guix-devel <at> gnu.org` and look for *sponsors*: one
or more people who will support the GCD and participate in discussions
by your side (see below).
The GCD is now in *draft* state and will be *submitted* once it has at
least one sponsor in addition to the author(s). See “Submission Period”
below.
## Roles
- An *author* is the person or one of the persons submitting the GCD.
Authors bear the responsibility to carry out the process to its
conclusion.
- A *sponsor* is a contributor who, during the submission period (see
below), informs the author(s) that they would like to support the GCD
by participating in discussions, providing constructive comments to
help the author(s), soliciting opinions, and acting as timekeepers. As
a sponsor, please make sure that all participants have the time and
space for expressing their comments.
Sponsors should be contributors who consider being sufficiently
familiar with the project’s practices; hence it is recommended, but not
mandatory, to be a team member.
- A *team member* is the member of a team, as defined in the [Teams
section of the GNU Guix Reference
Manual](https://guix.gnu.org/manual/devel/en/html_node/Teams.html).
Currently, the list of teams and their members is maintained in the
file `etc/teams.scm` in the [GNU Guix
repository](https://git.savannah.gnu.org/cgit/guix.git/tree/etc/teams.scm)
- A *contributor* is a person who has been participating in Guix
activities, for instance by writing or reviewing code, by supporting
users on fora, or by contributing to translations.
## Communication Channels
- The *draft* is sent by email to `guix-devel <at> gnu.org`.
- Once *submitted*, the GCD is announced to `info-guix <at> gnu.org` and discussed
using the assigned issue number.
- The *final* document is published to `info-guix <at> gnu.org` and the
deliberating replies are sent to the assigned issue number.
## Timeline
A GCD must follow the process illustrated by the diagram below,
consisting of several *periods*.
```
draft submitted final
+--------------------+ +---------------------+ +---------------------+
| Submission Period | | Discussion Period | | Deliberation Period |
| (up to 7 days) |-X->| (30–60 days) |-->| (14 days) |
+--------------------+ : +---------------------+ +---------------------+
: : : |
: v : |
: cancelled v |
: o-----------o |
+- - - - - - - - ->| Withdrawn |<----------------- X
o-----------o |
V
o----------o
| Accepted |
o----------o
```
The subsections below detail the various periods and their duration.
### Submission Period (up to 7 days)
Anyone can author and propose a GCD as a regular patch and look for
sponsors (see “Roles”). The GCD is *submitted* once one or more people
have volunteered to be sponsors by publicly replying “I sponsor”; it is
*cancelled* if no sponsor could be found during that period. The next step
is the *discussion period*.
Authors may withdraw their GCD at any time; they can resubmit it again
later (under a new GCD number).
### Discussion Period (at least 30 days, up to 60 days)
Once submitted, the GCD is publicly discussed by all the members of the
community. Authors are encouraged to publish updated versions
incorporating feedback during the discussion; members are encouraged to
share a summary of their main concerns or opposition, if any, for being
included under section “Open Issues” in the document.
When deemed appropriate, between 30 days and 60 days after the start of the
discussion period, the author(s) may publish a final version and announce
the start of the *deliberation period*. If the authors fail to do so, the
deliberation period automatically starts 60 days after the start of the
discussion period based on the latest version provided by the author(s).
### Deliberation Period (14 days)
Deliberation aims at consolidating consensus; see “Decision Making” below.
The *deliberation period* starts when the authors publish a final version
of the GCD at `info-guix <at> gnu.org`. Anyone who is a team member is a
deliberating member and is encouraged to contribute to the deliberation.
Once the final version is published, 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. A team member sending this reply should have made constructive
comments during the discussion period.
The GCD is *accepted* if (1) at least 25% of all team members–as of the
start of the “Deliberation Period”–send a reply, and (2) no one
disapproves. In other cases, the GCD is *withdrawn*.
GCD acceptance is not a rubber stamp; in particular, it does not mean the
proposal will effectively be implemented, but it does mean that all the
participants consent to its implementation.
Similarly, withdrawal does not necessarily equate with rejection; it could
mean that more discussion and thought is needed before ideas in the GCD are
accepted by the community.
## Decision Making
Contributors and even more so team members are expected to help build
consensus. By using consensus, we are committed to finding solutions that
everyone can live with.
Thus, no decision is made against significant concerns; these concerns are
actively resolved through counter proposals. A deliberating member
disapproving a proposal bears a responsibility for finding alternatives,
proposing ideas or code, or explaining the rationale for the status quo.
To learn what consensus decision making means and understand its finer
details, you are encouraged to read
<https://www.seedsforchange.org.uk/consensus>.
## Merging GCDs
Whether it is accepted or withdrawn, a person with commit rights merges the
GCD following these steps:
1. Fill in the remaining metadata in the GCD headers (changing the `status`
to `accepted` or `withdrawn`; adding the URL of the discussion in the
`discussion` header; updating the `date` header; if previously-accepted
GCDs are deprecated by this new GCD, change the `status` header
accordingly with `deprecated`);
2. Commit everything;
3. Announce the publication of the GCD.
All the GCDs are dual-licensed under the [Creative Commons
Attribution-ShareAlike
4.0](https://creativecommons.org/licenses/by-sa/4.0/) license and the [GNU
Free Documentation License 1.3, with no Invariant Sections, no Front-Cover
Texts, and no Back-Cover Texts](https://www.gnu.org/licenses/fdl-1.3.html)
or (at your option) any later version.
## GCD Template
The expected structure of GCDs is captured by the template file
`000-template.md`, written in English with Markdown syntax.
## Cost of Reverting
Not applicable. Please note that the GCD process described in this
document can be amended by subsequent GCDs.
## Drawbacks
There is a risk that the additional process may hinder or burden
contributions, potentially causing more harm than good. We should stay
alert that the process is only a way to help contribution, not an end in
itself.
Discussions could easily have a low signal-to-noise ratio. We will
collectively pay attention to over- and under-representation of voices and
notably avoid repeating arguments, avoid using exclusionary jargon, and
solicit opinions from those who remained silent.
## Open Issues
There are still questions regarding the desired scope of the process.
While we want to ensure that technical changes affecting users are
well-considered, we certainly don’t want the process to become unduly
burdensome. This is a delicate balance which will require care to maintain
moving forward.
[Message part 4 (text/plain, inline)]
-- --
[000-template.md (text/markdown, inline)]
title: <Name Of The Proposal> id: <the next available number> status: <draft|submitted|accepted|withdrawn|deprecated> discussion: https://issues.guix.gnu.org/<number assigned by issue tracker> authors: <Author Name> sponsors: <Sponsor Name> date: <date when the discussion period starts> SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-only --- # Summary A one-paragraph explanation: motivation and proposed solution. # Motivation Describe the problem(s) this GCD attempts to address as clearly as possible and optionally give an example. Explain how the status quo is insufficient or not ideal. # Detailed Design Main part. The sections compares this solution to other options, including the status quo, and describes the various tradeoffs in this space. Explain details, corner cases, provide examples. Explain it so that someone familiar can understand. It is best to exemplify, including with contrived examples. If the Motivation section describes something that is hard to do without this proposal, this is a good place to show how easy that thing is to do with the proposed solution. ## Cost of Reverting This section explains the impact on users and/or community members of the proposed change, and estimates the effort it would take to revert it. For code changes, assess the expected impact on existing code or processes on the following scale: 0. No incompatibility 1. Incompatible only in extremely rare cases (corner cases) 2. Incompatible in rare cases (only visible to advanced users) 3. Unavoidable incompatibility (affecting most) Describe the migration path and consider how to follow the Deprecation Policy of the project. For non-coding activities such as processes of the project, similarly explain what impact they will have on workflows. How will your proposed change evolve over time? What is the cost of changing or reverting the approach later? # Drawbacks and Open Issues At submission time, be upfront about open issues so others in the community can help. At the end of the process, this section might be empty. If not, please be explicit with the known issues and potential directions to address them.
[Message part 6 (text/plain, inline)]
--
PS: The very first draft had been sent more than one year ago [1,2].
Then we discussed this topics at Guix Days 2024 [3]. Noé resumed
[4] on December (more than 40 days ago) and several updates had been
sent to guix-devel; see v5 [5], v6 [6], v7 [7] etc. v10 [8]. A
consensus had been reached.
The discussion is tracked in:
https://issues.guix.gnu.org/74736
1: Request-For-Comment process: concrete implementation
Simon Tournier <zimon.toutoune <at> gmail.com>
Tue, 31 Oct 2023 12:14:42 +0100
id:87h6m7yrfh.fsf <at> gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-10
https://yhetil.org/guix/87h6m7yrfh.fsf <at> gmail.com
2: [bug#66844] [PATCH 0/1] Add Request-For-Comment process.
Simon Tournier <zimon.toutoune <at> gmail.com>
Tue, 31 Oct 2023 12:05:22 +0100
id:cover.1698747252.git.zimon.toutoune <at> gmail.com
https://issues.guix.gnu.org/66844
https://issues.guix.gnu.org/msgid/cover.1698747252.git.zimon.toutoune <at> gmail.com
https://yhetil.org/guix/cover.1698747252.git.zimon.toutoune <at> gmail.com
3: https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/guix-days-2024/governance.org?id=12a5d469852a008c314c5f30d17ce60f5a954325
4: [bug#74736] [PATCH v2 0/1] Add Request-For-Comment process.
Noé Lopez via Guix-patches via <guix-patches <at> gnu.org>
Sun, 08 Dec 2024 13:29:52 +0100
id:cover.1733614983.git.noelopez <at> free.fr
https://issues.guix.gnu.org/74736
https://issues.guix.gnu.org/msgid/cover.1733614983.git.noelopez <at> free.fr
https://yhetil.org/guix/cover.1733614983.git.noelopez <at> free.fr
5: Request-For-Comment process: concrete implementation (v5)
Simon Tournier <zimon.toutoune <at> gmail.com>
Fri, 03 Jan 2025 19:38:01 +0100
id:87ttafn3p2.fsf <at> gmail.com
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/87ttafn3p2.fsf <at> gmail.com
6: Re: Request-For-Comment process: concrete implementation (v5)
Ludovic Courtès <ludo <at> gnu.org>
Tue, 07 Jan 2025 11:40:11 +0100
id:87zfk229h0.fsf <at> gnu.org
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/87zfk229h0.fsf <at> gnu.org
7: Guix Common Document process (v7) (was: Request-For-Comment, RFC)
Simon Tournier <zimon.toutoune <at> gmail.com>
Fri, 10 Jan 2025 01:07:47 +0100
id:87bjwfh6p8.fsf <at> gmail.com
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/87bjwfh6p8.fsf <at> gmail.com
8: Guix Consensus Document process (v10)
Simon Tournier <zimon.toutoune <at> gmail.com>
Fri, 17 Jan 2025 02:06:23 +0100
id:87bjw6mepc.fsf <at> gmail.com
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/87bjw6mepc.fsf <at> gmail.com
[Message part 7 (text/plain, inline)]
-------------------- End of forwarded message --------------------
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.