Guix Consensus DocumentsHome

Guix Consensus Document Process

by Simon Tournier, Noé Lopez, Ludovic Courtès —
sponsored by pukkamustard, Ricardo Wurmus

Accepted

Timeline

08 December
drafting08 December
discussion22 January
deliberation05 February
accepted

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.

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@gnu.org.
  5. Announce your GCD at guix-devel@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. Currently, the list of teams and their members is maintained in the file etc/teams.scm in the GNU Guix repository

  • 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@gnu.org.

  • Once submitted, the GCD is announced to info-guix@gnu.org and discussed using the assigned issue number.

  • The final document is published to info-guix@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@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 license and the GNU Free Documentation License 1.3, with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts 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.