Subject: Do you read it? (was: [bug#74736] [PATCH v9] Add Guix Consensus Document process)

From: Simon Tournier <[email-masked]>
Date: Fri, 17 Jan 2025 00:13:45 +0100

Hi,

The number v9 of my message is superseded by Hartmut message:

        [bug#74736] [PATCH v2 0/1] Add Request-For-Comment process.
        Hartmut Goebel <[email-masked]>
        Thu, 16 Jan 2025 21:41:26 +0100
        id:[email-masked]
        https://issues.guix.gnu.org/74736
        https://issues.guix.gnu.org/msgid/[email-masked]
        https://yhetil.org/guix/[email-masked]

BTW, that’s weird!  The message with the header below appears in my Sent
folder (Gmail webinterface) but has not reached the list.  Hum?

--8<---------------cut here---------------start------------->8---
From: Simon Tournier <[email-masked]>
To: [email-masked]
Cc: =?utf-8?Q?No=C3=A9?= Lopez <[email-masked]>, Ludovic =?utf-8?Q?Court?=
 =?utf-8?Q?=C3=A8s?= <[email-masked]>,
 Christopher Baines <[email-masked]>, "Artyom V. Poptsov"
 <[email-masked]>, Suhail Singh <[email-masked]>,
 "pukkamustard" <[email-masked]>, Vagrant Cascadian
 <[email-masked]>, Janneke Nieuwenhuizen <[email-masked]>, Ricardo
 Wurmus <[email-masked]>, Hartmut Goebel
 <[email-masked]>, Efraim Flashner <[email-masked]>,
 [email-masked], Andreas Enge <[email-masked]>, GNU Guix maintainers
 <[email-masked]>
Subject: [bug#74736] [PATCH v9] Add Guix Consensus Document process
Date: Thu, 16 Jan 2025 18:55:53 +0100

--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
--8<---------------cut here---------------end--------------->8---

Cheers,
simon

On Thu, 16 Jan 2025 at 18:55, Simon Tournier <[email-masked]> wrote:
> Hi,
>
> Please find attach the v9;  I hope it addresses the comments.
>
> Attached the diff and the document.  The minor changes are:
>
>  • Point alone “1. Clone …”
>
>  • Replace remaining RFC with GCD.
>
>  • Add a sentence about “Sponsor” role.
>
>  • Add the role of “Contributor”.
>
>  • Tweak the artist view of the Timeline
>
>  • Explicit mention that everyone can participate to the “Discussion
>    Period”.  And mention that the main concerns and/or opposition are
>    collected to the final document.
>
>  • Move upfront the aim of “Deliberation Period”.  Remove a redundant
>    sentence.
>
>  • Explicit mention the state ‘deprecated’.
>
>
> WDYT?
>
> Cheers,
> simon
>
> --
>
> diff -u /tmp/001-gcd-process-v8.md /tmp/001-gcd-process-v9.md
> --- /tmp/001-gcd-process-v8.md	2025-01-16 16:51:08.758030546 +0100
> +++ /tmp/001-gcd-process-v9.md	2025-01-16 18:43:01.835296714 +0100
> @@ -73,7 +73,7 @@
>  ## How the Process Works
>
>  1. Clone
> -   https://git.savannah.gnu.org/git/guix/guix-consensus-documents.git .
> +   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’s structure.  The GCD must not
> @@ -92,15 +92,16 @@
>
>  ## Roles
>
> -  - An *author* is the person or one of the persons submitting the RFC.
> +  - 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
> -    RFC by participating in discussions, providing constructive comments
> +    GCD by participating in discussions, providing constructive comments
>      to help the author(s), soliciting opinions, and acting as
> -    timekeepers.
> +    timekeepers.  As a sponsor, please make sure that all 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
> @@ -111,6 +112,10 @@
>      members is maintained in the file `etc/teams.scm` in the Guix
>      repository.
>
> +  - A *contributor* is a person contributing to Guix either with code,
> +    translation, reviewing, etc. and more broadly any person feeling part
> +    of the Guix community.
> +
>  ## Timeline
>
>  A GCD must follow the process illustrated by the diagram below,
> @@ -118,21 +123,20 @@
>
>
>  ```
> -                         +-----------+
> -          +- - - - - - ->| Withdrawn |<----------------------+
> -          :              +-----------+                       |
> -          :                    ^                             |
> -          :                    :                             |
> -+--------------------+   +---------------------+   +---------------------+
> -| Submission Period	 |   |  Discussion Period  |   | Deliberation Period |
> -|  (up to 7 days)    |-->|   (30–60 days)      |-->|     (14 days)		 |
> -+--------------------+   +---------------------+   +---------------------+
> -                                                             |
> -                                                             |
> ++--------------------+    +---------------------+   +---------------------+
> +| Submission Period  |    |  Discussion Period  |   | Deliberation Period |
> +|  (up to 7 days)    |-X->|   (30–60 days)      |-->|     (14 days)	      |
> ++--------------------+ :  +---------------------+   +---------------------+
> +          :            :           :                         |
> +          :            v           :                         |
> +          :         declined       v                         |
> +          :                  o-----------o                   |
> +          +- - - - - - - - ->| Withdrawn |<----------------- X
> +                             o-----------o                   |
>                                                               V
> -                                                       +----------+
> -                                                       | Accepted |
> -                                                       +----------+
> +                                                        o----------o
> +                                                        | Accepted |
> +                                                        o----------o
>  ```
>
>  The subsections below detail the various periods and their duration.
> @@ -150,8 +154,11 @@
>
>  ### Discussion Period (at least 30 days, up to 60 days)
>
> -Once submitted, the GCD is publicly discussed; authors are encouraged to
> -publish updated versions incorporating feedback during the discussion.
> +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
> @@ -159,8 +166,11 @@
>
>  ### Deliberation Period (14 days)
>
> -All team members can participate in deliberation and are encouraged to
> -do so.
> +Deliberation aims at consolidating consensus; see “Decision Making”
> +below.
> +
> +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:
> @@ -176,13 +186,6 @@
>  reply, and (2) no one disapproves.  In other cases, the GCD is
>  *withdrawn*.
>
> -Deliberation aims at consolidating consensus; see “Decision Making”
> -below.
> -
> -Anyone who is a team member is a deliberating member and is encouraged
> -to contribute to the deliberation.  Team members are defined by the
> -file etc/teams.scm (see “Teams” in the manual).
> -
>  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.
> @@ -215,7 +218,7 @@
>     `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);
> +   `status` header accordingly with `deprecated`);
>  2. committing everything;
>  3. announcing the publication of the GCD.
>
>
> Diff finished.  Thu Jan 16 18:44:37 2025
>
> --
>
> 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-submitted: 2024-12-12
> date: 2025-01-15
> 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
> Guix project.  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 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, etc.).
>
> # 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
> by the manual in its “Contributing” chapter.
>
> ## How the Process Works
>
> 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’s structure.  The GCD must not
>    be prospective; it must formalize an idea and sketch a plan to
>    implement it, even if not all details are known.  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 *submitted* once it has at least one sponsor in addition to
> the author(s).  See “Submission Period” below.
>
> Submitted GCD is announced at [email-masked]`.
>
> ## 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 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 by the Guix
>     project in the manual.  Currently, the list of teams and their
>     members is maintained in the file `etc/teams.scm` in the Guix
>     repository.
>
>   - A *contributor* is a person contributing to Guix either with code,
>     translation, reviewing, etc. and more broadly any person feeling part
>     of the Guix community.
>
> ## Timeline
>
> A GCD must follow the process illustrated by the diagram below,
> consisting of several *periods*.
>
>
> ```
> +--------------------+    +---------------------+   +---------------------+
> | Submission Period  |    |  Discussion Period  |   | Deliberation Period |
> |  (up to 7 days)    |-X->|   (30–60 days)      |-->|     (14 days)	      |
> +--------------------+ :  +---------------------+   +---------------------+
>           :            :           :                         |
>           :            v           :                         |
>           :         declined       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 submit a GCD as a regular patch and look for
> sponsors (see below).  The GCD is *submitted* once one or more people
> have volunteered to be sponsors by publicly replying “I sponsor”; it is
> canceled 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, possibly 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*.
>
> ### Deliberation Period (14 days)
>
> Deliberation aims at consolidating consensus; see “Decision Making”
> below.
>
> 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 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 Final GCDs
>
> Whether it is accepted or withdrawn, a committer merges the final GCD
> following these steps:
>
> 1. filling 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. committing everything;
> 3. announcing 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 in the file
> `000-template.md`, written in English with Markdown syntax.
>
> ## Cost of Reverting
>
> The GCD process described in this document can be amended by subsequent
> GCDs.
>
> ## Drawbacks
>
> There is a risk that the additional process will hinder contribution more than
> it would help.  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 of 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 that affect users are
> well-considered, we certainly don’t want the process to become unduly
> burdensome.  This is a careful balance which will require care to
> maintain moving forward.