GNU bug report logs - #74736
[PATCH v2 0/1] Add Request-For-Comment process.

Previous Next

Full log

View this message in rfc822 format

From: Andrew Tropin <andrew <at> trop.in>
To: Simon Tournier <zimon.toutoune <at> gmail.com>, info-guix <at> gnu.org, 74736 <at> debbugs.gnu.org
Subject: [bug#74736] Guix Consensus Document process – deliberation
Date: Fri, 31 Jan 2025 13:16:07 +0400

[Message part 1 (text/plain, inline)]

On 2025-01-22 20:44, Simon Tournier wrote:

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

I support.

Thank you very much for all the effort, GCD looks really good.

P.S. The first reply was marked as spam by debbugs, this is a second
attempt to send it.

-- 
Best regards,
Andrew Tropin

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.