[bug#74736,v10] Add Guix Consensus Document process
Commit Message
Hi,
I sent v9 (Message-ID: 8734hiskwm.fsf@gmail.com) but that has not
reached the list, hum?! And Hartmut sent a diff as v9, hence v10. :-)
Changes compared to v8:
• Changed some level for the subtitles. And added “Getting Started”.
• Removed trailing dot after repository URL.
• Reworded ’prospective’.
• Removed redundant information about “submitted” and pointed to the
dedicated section. Clarified using the term “draft”.
• Replaced the term RFC by GCD.
• Added a sentence about the role of “Sponsor”. And added a
“Contributor” role. The idea is to rely on that term for clarifying
“author” and who can discuss. But then, the term does not appear…
• Add section “Channel of Communication”.
• Revamped the artist view of the timeline.
• Minor tweaks under “Submission Period”.
• Minor tweaks under “Discussion Period”. Added a paragraph to deal
with the case where “Author” and “Sponsor” vanish.
• Minor tweaks under “Deliberation Period”: moved sentence; removed
redundant information.
• Minor tweaks under “Merging GCD”.
WDYT?
Cheers,
simon
--
--
Comments
Hi Simon and others!
Thanks for the good work. I've been struggling keeping pace with it, ah!
I liked it already a year ago, and I like it more now, thanks to the
various refinements brought to it in this thread. Below are small typos
I've spotted and other suggestions.
Simon Tournier <zimon.toutoune@gmail.com> writes:
[...]
> 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
GNU Guix project, later referenced as either Guix or "the project", for
brevity.
> structured way to propose, discuss, and decide on major changes
> affecting the project. It aims to draw attention of community members
the attention
> 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
Why quote "significant" ?
> 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
Ditto.
> 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.).
Punctuaction rule: I seem to recall that you don't need a trailing dot
if there is already one, even inside a preceding closing parens [0].
[0] https://english.stackexchange.com/a/8385
> # Detailed Design
>
> ## When to Follow This Process
>
> The GCD process applies only to “significant” changes, which include:
The quotes here, again.
> - 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.
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’s structure. The GCD must
I'd use just 'template structure', without 's
> 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
Maybe use *draft* instead of quotes, for emphasis, if deemed necessary.
> one sponsor in addition to the author(s). See “Submission Period” below.
Markdown (or at least most flavors in use of it) supports referring to
sections via URL, IIRC. So I'd use:
--8<---------------cut here---------------start------------->8---
See [Submission Period](#submission-period) below.
--8<---------------cut here---------------end--------------->8---
Taking care to add the #submission-period custom id if our parser
doesn't do so automatically. [1]
[1] https://www.markdownguide.org/extended-syntax/#heading-ids
>
> ## 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
all *participants*
> 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
as defined in the [Teams section of the GNU Guix Reference Manual](https://guix.gnu.org/manual/devel/en/html_node/Teams.html).
> members is maintained in the file `etc/teams.scm` in the Guix
> repository.
[GNU Guix repository](https://git.savannah.gnu.org/cgit/guix.git/tree/etc/teams.scm)
>
> - 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.
>
> ## Channels of Communication
>
> - The *draft* is sent 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 : |
> : canceled v |
s/canceled/cancelled/
> : 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
> *canceled* if no sponsor could be found during that period. The next step
s/canceled/cancelled/
> 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 after 60 days, a final version is not yet published, then a grace period
> of 14 days is granted. Finally the GCD is considered as *stale* and the last
> update is picked for the final version.
>
> ### 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 GCD
>
> Whether it is accepted or withdrawn, a person who has commit permission
> to the GCD repository merges the 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
Instead of ing form, I'd just use imperative for these steps, which is
more concise and in line with how we document code already.
s/filling/fill/
> 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;
s/committing/Commit an push the resulting document/
> 3. announcing the publication of the GCD.
s/announcing/announce/
> 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
by the template 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.
This section name (Cost of Reverting) doesn't match with its content?
> ## Drawbacks
>
> There is a risk that the additional process will hinder contribution more than
> it would help.
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
s/over-/over/ ?
> and notably avoid repeating arguments, avoid using exclusionary jargon,
> and solicit opinions of those who remained silent.
s/of those/from those/
> ## 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
s/that affect users/affecting users/
> well-considered, we certainly don’t want the process to become unduly
> burdensome. This is a careful balance which will require care to
s/careful/delicate/, to avoid repeating 'care' twice.
Assuming my above comments are addressed,
Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail>
Hello,
Just one note:
Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>> The GCD process is a mechanism to determine whether a proposed change is
>> “significant” enough to require attention from the community at large
>
> Why quote "significant" ?
To me, this is to emphasize that what is meant by “significant” will be
clarified below.
(Thanks for all the other comments and suggestions!)
Ludo’.
Hi,
Ludovic Courtès <ludo@gnu.org> writes:
> Hello,
>
> Just one note:
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>>> The GCD process is a mechanism to determine whether a proposed change is
>>> “significant” enough to require attention from the community at large
>>
>> Why quote "significant" ?
>
> To me, this is to emphasize that what is meant by “significant” will be
> clarified below.
OK. That wasn't clear to me. I'd suggest wording that explicitly, for
example:
--8<---------------cut here---------------start------------->8---
[...] a proposed change is "significant" (which meaning is clarified
below)
--8<---------------cut here---------------end--------------->8---
or similar.
> (Thanks for all the other comments and suggestions!)
My pleasure!
Happy 2025!
Hi Maxim,
Thanks for your comments. All included except one.
On Mon, 20 Jan 2025 at 11:50, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>> - changing the contributor workflow and related infrastructure (mailing
>> lists, source code repository and forge, continuous integration, etc.).
>
> Punctuaction rule: I seem to recall that you don't need a trailing dot
> if there is already one, even inside a preceding closing parens [0].
>
> [0] https://english.stackexchange.com/a/8385
Hum, I think here etc. does not act as the last term of the sentence
because it’s inside the parenthesis. It does not appear to me a
double-duty case.
Anyway, in doubt I replaced by ’and so on’. :-)
>> The GCD process applies only to “significant” changes, which include:
>
> The quotes here, again.
Replaced by *significant*, thus it’s consistent with the rest.
>> one sponsor in addition to the author(s). See “Submission Period” below.
>
> Markdown (or at least most flavors in use of it) supports referring to
> sections via URL, IIRC. So I'd use:
>
> --8<---------------cut here---------------start------------->8---
> See [Submission Period](#submission-period) below.
> --8<---------------cut here---------------end--------------->8---
Since it makes the document in plain text harder to read and it does not
bring much, and we do not know yet how these GCDs will be parsed, it
appears to me simpler to keep it that way, for now.
>> ## Cost of Reverting
>>
>> The GCD process described in this document can be amended by subsequent
>> GCDs.
>
> This section name (Cost of Reverting) doesn't match with its content?
I added “Not applicable” because it’s hard to predict the cost of
reverting about something that we have never tried. :-)
Cheers,
simon
Hi,
On Tue, 21 Jan 2025 at 08:47, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>> To me, this is to emphasize that what is meant by “significant” will be
>> clarified below.
>
> OK. That wasn't clear to me. I'd suggest wording that explicitly, for
> example:
>
> --8<---------------cut here---------------start------------->8---
> [...] a proposed change is "significant" (which meaning is clarified
> below)
> --8<---------------cut here---------------end--------------->8---
>
> or similar.
I emphasized with *significant* because it’s consistent with the rest
(*draft*, *submitted*, *periods*, etc.).
Cheers,
simon
@@ -70,37 +70,39 @@
These day-to-day contributions remain governed by the process described
by the manual in its “Contributing” chapter.
-## How the Process Works
+# How the Process Works
+
+## Getting Started
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
- 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
+3. Write your GCD following the template’s 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 *submitted* once it has at least one sponsor in addition to
-the author(s). See “Submission Period” below.
-
-Submitted GCD is announced at `info-guix@gnu.org`.
+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 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 +113,20 @@
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.
+
+## Channels of Communication
+
+ - The *draft* is sent 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,
@@ -118,49 +134,60 @@
```
- +-----------+
- +- - - - - - ->| Withdrawn |<----------------------+
- : +-----------+ |
- : ^ |
- : : |
-+--------------------+ +---------------------+ +---------------------+
-| Submission Period | | Discussion Period | | Deliberation Period |
-| (up to 7 days) |-->| (30–60 days) |-->| (14 days) |
-+--------------------+ +---------------------+ +---------------------+
- |
- |
+ draft submitted final
++--------------------+ +---------------------+ +---------------------+
+| Submission Period | | Discussion Period | | Deliberation Period |
+| (up to 7 days) |-X->| (30–60 days) |-->| (14 days) |
++--------------------+ : +---------------------+ +---------------------+
+ : : : |
+ : v : |
+ : canceled v |
+ : o-----------o |
+ +- - - - - - - - ->| Withdrawn |<----------------- X
+ o-----------o |
V
- +----------+
- | Accepted |
- +----------+
+ 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
+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
-canceled if no sponsor could be found during that period. The next step
+*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.
+later (under a new GCD number).
### 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
announce the start of the *deliberation period*.
+If after 60 days, a final version is not yet published, then a grace period
+of 14 days is granted. Finally the GCD is considered as *stale* and the last
+update is picked for the final version.
+
### 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.
+
+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:
@@ -172,16 +199,9 @@
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*.
-
-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).
+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
@@ -206,16 +226,16 @@
details, you are encouraged to read
<https://www.seedsforchange.org.uk/consensus>.
-## Merging Final GCDs
+## Merging GCD
-Whether it is accepted or withdrawn, a committer merges the final GCD
-following these steps:
+Whether it is accepted or withdrawn, a person who has commit permission
+to the GCD repository merges the 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);
+ `status` header accordingly with `deprecated`);
2. committing everything;
3. announcing the publication of the GCD.