[bug#74736] [PATCH v6] Add Request-for-Comments process.

["Noé Lopez via Guix-patches via" <guix-patches@gnu.org>]

Ludovic Courtès <ludo@gnu.org> writes:

> Hello,
>
> As proposed before, here’s a reworked version based on v5.  The intent
> is to keep the spirit and process unchanged compared to v5, while making
> the document a bit more concise (239 lines, v5 was 322), improving
> consistency for key words, hopefully improving wording, fixing
> grammatical issues, and adding Markdown ornaments where appropriate.
>
> Notable changes:
>
>   • Instead of “supporter” and “co-supporter”, I propose “author(s)” and
>     “supporter(s)” (there must be at least one supporter).
>
>   • Explicitly state the license of RFCs (CC-BY-SA or GFDL).
>
>   • Clarify that the deliberation period lasts exactly 14 days (was “up
>     to 14 days” in one place, “14 days” in another).
>
>   • Consistently name the different periods.
>
>   • Remove mention of the ‘withdrawn/’ directory: it’s redundant with
>     the ‘status’ header.
>
>   • Clarify what to do with “deprecated” RFCs.
>
>   • Clarify headers of this RFC.
>
>   • Clarify that this is not just for technical changes.
>   
> I can proofread and possibly propose minor tweaks the template
> afterwards.
>
> Thoughts?
>
> Ludo’.

This is great, thanks!  A few comments below:

>
> title: Requests-for-Comment Process
> id: 000

001, since the template takes id 0000 for ease of access.

> status: submitted
> discussion: https://issues.guix.gnu.org/74736
> authors: Simon Tournier, Noé Lopez, Ludovic Courtès
> supporters: ?
> submitted: 2024-12-12
> date: 2025-01-15

It’s a good place to add:
SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-only

> ---
>
> # Summary
>
> This document describes the _request for comments_ (RFC) process of the
> Guix project.  The RFC 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 RFC 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.)

Missing a dot at the end of the sentence.

> # Detailed Design
>
> ## When to Follow This Process
>
> The RFC 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
> RFC first.
>
> Most day-to-day contributions do *not* require an RFC; 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/requests-for-comments.git .

Why the alone dot?

> 2. Copy `0000-template.md` to `00XY-short-name.md` where `short-name`
>    is a short descriptive name long and `XY` is the sequence number.
> 3. Write your RFC following the template’s structure.  The RFC 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 RFC, it must explicitly say so.
> 4. Submit the RFC as a patch to `guix-patches@gnu.org`.
> 5. Announce your RFC at `guix-devel@gnu.org` and look for *supporters*:
>    one or more people who will support the RFC and participate in
>    discussions by your side (see below).
>
> The RFC is *submitted* once it has at least one supporter in addition to
> the author(s).
>

So we are now three authors and no supporters for this RFC?  Could we
say that more than one author also works for submitting?

> ## Supporters
>
> A supporter is a contributor sufficiently familiar with the project’s
> practices, hence it is recommended, but not mandatory, to be a team
> member.  Supporters do not have to agree with all the points of the RFC
> but should generally be satisfied that the proposed additions are a good
> thing for the community.
>
> Supporters help the author(s) by participating in discussions, amending
> the document as it is being discussed, and acting as timekeepers.
>
> ## Timeline
>
> The lifetime of an RFC is structured into the following recommended
> periods:
>
> ![diagram.svg](Diagram of the RFC process.)
>
> ```dot <- TODO: make this a separate file
> digraph "RFC Timeline" {
>     submission[label=<Submission Period<br />up to 7 days>]
>     comments[label=<Discussion Period<br />30–60 days>]
>     deliberation[label=<Deliberation Period<br />14 days>]
>     withdrawn[label=Withdrawn, shape=rectangle]
>     final[label=Final, shape=rectangle]
>     
>     submission -> comments
>     submission -> withdrawn
>     comments -> deliberation
>     deliberation -> withdrawn
>     deliberation -> final
>     
>     withdrawn -> submission [label="New version"]
>     
>     comments -> withdrawn
> }
> ```
>
> The subsections below detail the various stages and their duration.
>
> ### Submission Period (up to 7 days)
>
> Anyone can author and submit an RFC as a regular patch and look for
> supporters (see below).  The RFC is *submitted* once it has one or more
> supporters; the next step is the *discussion period*.
>
> Author(s) may withdraw their RFC at any time; they can resubmit it again
> later, possibly under a new RFC number.
>
> ### Discussion Period (at least 30 days, up to 60 days)
>
> Once submitted, the RFC is publicly discussed; authors are encouraged to
> publish updated versions incorporating feedback during the discussion.
>
> Once the discussion settles, at the latest after 60 days, the author(s)
> publish a final version, leading to the *deliberation period*.
>
> ### Deliberation Period (14 days)
>
> All members of any team of the Guix project can participate in
> deliberation and are encouraged to do so.
>
> 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 RFC:
>
> - “I support”, meaning that one supports the proposal);

This parenthesis is alone.

> - “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 must have actively
>   proposed alternative solutions during the discussion period.
>
> The RFC is *accepted* if (1) at least 25% of all team members send a
> reply, and (2) no one disagrees.  In other cases, the RFC is
> *withdrawn*.
>
> Deliberation aims at consolidating consensus; see “Decision Making”
> below.
>
> RFC 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 RFC 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 .

Another alone dot 🤔

>
> ## Merging Final RFCs
>
> Whether it is accepted or withdrawn, a committer merges the final RFC
> following these steps:
>
> 1. filling in the remaining metadata in the RFC 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 RFCs are deprecated by this new RFC, change the
>    `status` header accordingly);
> 2. committing everything;
> 3. announcing the publication of the RFC.
>
> All the RFCs 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).

I would add “or (at your option) any later version.”

>
> ## RFC Template
>
> The expected structure of RFCs is captured by the template in the file
> `0000-template.md`, written in English with Markdown ornaments.

Ornament is a complicated word, I would replace it with “syntax”.

>
> ## Cost of Reverting
>
> The RFC process described in this documented can be amended by
> subsequent RFCs.
>
> ## 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.

Thanks for the v6, apart from my comments I think its great and ready to
be submitted :)

In my opinion there are too many unnecessary emphasis (mostly with `),
but I will live with it.

Have a nice day,
Noé