Subject: [FWD] Guix Consensus Document process –deliberation

From: Simon Tournier <[email-masked]>
Date: Wed, 22 Jan 2025 20:49:55 +0100

Repost because “550 This message scored 18.0 spam points.”

-------------------- Start of forwarded message --------------------
From: Simon Tournier <[email-masked]>
To: [email-masked], [email-masked]
Cc: [...]
    all teams members
  + all people with commit access  

Subject: Guix Consensus Document process – deliberation
Date: Wed, 22 Jan 2025 20:44:08 +0100

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 [email-masked] 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

--
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 [email-masked]`.
5. Announce your GCD at [email-masked]` 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 [email-masked]`.
 
 - Once *submitted*, the GCD is announced to [email-masked]` and discussed
   using the assigned issue number.
   
 - The *final* document is published to [email-masked]` 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 [email-masked]`.  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.
--

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

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 <[email-masked]>
Tue, 31 Oct 2023 12:14:42 +0100
id:[email-masked]
https://lists.gnu.org/archive/html/guix-devel/2023-10
https://yhetil.org/guix/[email-masked]

2: [bug#66844] [PATCH 0/1] Add Request-For-Comment process.
Simon Tournier <[email-masked]>
Tue, 31 Oct 2023 12:05:22 +0100
id:[email-masked]
https://issues.guix.gnu.org/66844
https://issues.guix.gnu.org/msgid/[email-masked]
https://yhetil.org/guix/[email-masked]

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 <[email-masked]>
Sun, 08 Dec 2024 13:29:52 +0100
id:[email-masked]
https://issues.guix.gnu.org/74736
https://issues.guix.gnu.org/msgid/[email-masked]
https://yhetil.org/guix/[email-masked]

5: Request-For-Comment process: concrete implementation (v5)
Simon Tournier <[email-masked]>
Fri, 03 Jan 2025 19:38:01 +0100
id:[email-masked]
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/[email-masked]

6: Re: Request-For-Comment process: concrete implementation (v5)
Ludovic Courtès <[email-masked]>
Tue, 07 Jan 2025 11:40:11 +0100
id:[email-masked]
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/[email-masked]

7: Guix Common Document process (v7) (was: Request-For-Comment, RFC)
Simon Tournier <[email-masked]>
Fri, 10 Jan 2025 01:07:47 +0100
id:[email-masked]
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/[email-masked]

8: Guix Consensus Document process (v10)
Simon Tournier <[email-masked]>
Fri, 17 Jan 2025 02:06:23 +0100
id:[email-masked]
https://lists.gnu.org/archive/html/guix-devel/2025-01
https://yhetil.org/guix/[email-masked]
-------------------- End of forwarded message --------------------