Subject: [bug#74736] [PATCH v2 0/1] Add Request-For-Comment process.

From: Ludovic Courtès <[email-masked]>
Date: Thu, 12 Dec 2024 19:14:31 +0100

Hi Noé,

Thanks a lot for resuming this work!  That’s the right thing to do.

Leaving out 000-rfc-template.txt for now.

Noé Lopez <[email-masked]> skribis:

> +++ b/rfc/0001-rfc-process.txt
> @@ -0,0 +1,232 @@
> +# -*- mode:org -*-
> +#+TITLE: Request-For-Comment process
> +#+DATE: 2023-10-31

[...]

> +* Motivation
> +
> +The current way that we add new features to Guix has been good for early
> +development, but it is starting to show its limits as Guix becomes a broadly
> +used system with many contributors.  Changes might be slowed down by the lack
> +of structure to acquire consensus.

“… to achieve consensus, lack of a central place to consult contributors
and users, and lack of clear deadlines.”

> +Note that this process does not cover most of the changes.  It covers
> +significant changes, for some examples:

“It covers proposals significant changes, where “significant” means any
change that could only be reverted at a high cost, or any change with
the potential to disrupt user scripts and programs or user workflows.
Examples include: ”

> + + change of inputs style
> +   (Removing input labels from package definitions, #49169)
> + + introduction of =guix shell= and deprecation of =guix environment=
> +   (Add 'guix shell' to subsume 'guix environment', #50960)
> + + introduction of authentication mechanism (Trustable "guix pull", #22883)
> + + changes in policy (Add "Deprecation Policy", #72840)
> + + collaboration via team and branch-features
> +   (several places mailing list guix-devel)

These are changes from the past that may long be forgotten by the time
we read them.  Perhaps we can abstract it a bit, like:

  - changing the <package> record type and/or its interfaces;
  - adding or removing a ‘guix’ sub-command;
  - changing the channel mechanism;
  - changing project 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.)

This list seems redundant with and similar to that under “When To Follow
This Process”; maybe just keep it in one place, under “When To Follow…”?

> +* Detail design

“Detailed Design”

> +** When you need to follow this process

“When To Follow This Process”

> +This process is followed when one intends to make "substantial" changes to the
> +Guix project.  What constitutes a "substantial" change is evolving based on
> +community norms, but may include the following.
> +
> +  + 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
> +  + Governance and changes to the way we collaborate
> +
> +Certain changes do not require an RFC:
> +
> +  - Adding, updating packages, removing outdated packages
> +  - Fixing security updates and bugs that don't break interfaces

I would add “General day-to-day contributions follow the regular
[decision-making process] and [team organization].”, with references to
the relevant sections of the manual.

> +A patch submission to Debbugs that contains any of the afore-mentioned

Typo: “aforementioned”.

I would remove “to Debbugs” to keep it more general and future-proof.

> +** How the process works
> +
> +  1. Clone https://git.savannah.gnu.org/git/guix.git

I would suggest a separate repo.

> +  2. Copy rfc/0000-template.org to rfc/00XY-good-name.org where good-name is
> +     descriptive but not too long and XY increments
> +  3. Fill RFC
> +  4. Submit to [email-masked]
> +  5. Announce your RFC to [email-masked]
> +
> +Make sure the proposal is as well-written as you would expect the final
> +version of it to be.  It does not mean that all the subtilities must be
> +considered at this point since that is the aim of review discussion.  It means
> +that the RFC process is not a prospective brainstorming and the proposal
> +formalize an idea for making it happen.
> +
> +The submission of a proposal does not require an implementation.  However, to
> +improve the chance of a successful RFC, it might be recommended to have an

s/it might be/it is/

> +Once supporter and co-supporter(s) are committed in the RFC process, the
> +review discussion starts.  Advertisement of the RFC on the mailing-lists
> +guix-devel is mandatory and IRC and other Guix communities are recommended.

“Publicizing of the RFC on the project’s main communication channels is
mandatory.”

> +After a number of rounds of review, the discussion should settle and a general
> +consensus should emerge.  If the RFC is successful then authors may contribute
> +to the implementation.  This bit is left intentionally vague and should be
> +refined in the future.

I’d drop it or write “See the ‘Decision Process and Timeline’ section
below.”

> +A successful RFC is not a rubber stamp, and in particular still does not mean
> +the feature will ultimately be merged; it does mean that in principle all the
> +major stakeholders have agreed to the feature and are amenable to merging it.

I’d write “all the participants” instead of “all the major
stakeholders”.

> +The Guix projects ensures that a team of co-supporters – the RFC team – remain
> +available for any new RFCs that don’t find any co-supporters.  This team
> +should be added to the etc/teams.scm file.

I would drop that.

> +** Timeline
> +
> +The lifetime of an RFC is structured into the following periods:
> +  submission (7d) ⟶ comments (30–60d) ⟶ last call (14d) ⟶ withdrawn OR final

Let’s borrow from the state transition diagram from at
<https://srfi.schemers.org/srfi-process.html>, for clarity.

Perhaps we should also shorten the text of each section below.

In each section heading, I would add its duration:

  *** Submission (up to 7 days)

  …

  *** Discussion (at least 30 days, up to 60 days)

  …

> +*** Comment
> +
> +The author publishes their RFC to guix-devel and starts a discussion period of

“The author publicizes their RFC, marking the start of a discussion
period of at least 30 days and at most 60 days.”

> +*** Last call
> +
> +The author publishes a final version of the RFC and a 14 day period is given
> +for people to express their agreement or disagreement.  If a positive
> +consensus is reached the RFC becomes final and the changes should be applied

“If consensus is reached, the RFC becomes …”

> +in less than six months.

I’m not sure what “the changes” refers to.

Regarding consensus, I would add a link to the “Making Decisions”
section of the manual…

> +** Decision making: consensus

… and drop this.

> +** Merging the outcome
> +
> +Once a consesus is made, a committer should do the following to merge the RFC:
> +
> + 1. Fill in the remaining metadata in the RFC header, including links for the
> +    original Debbugs submission.
> + 2. Commit everything.
> + 3. Announce the establishment of the RFC to all the stakeholders.
> + 4. Ensure the RFC is applied within six months.

Maybe we should define the role of “RFC editors” (or “RFC team”?), which
would be the people responsible for doing those changes.

> +** Template of RFC
> +
> +# Ludovic Courtès:
> +# I’d go for one format, preferably Markdown because we have a library to
> +# parse it.

Yes! :-)  Despite being an Org fan, I think we should stick to Markdown:
it’s widespread, well-known, and can be rendered by Haunt or by any
forge.

> +** Backward Compatibility
> +
> +None.
> +
> +** Forward compatibility

I’m not sure what’s expected in these sections.  Maybe “Compatibility
Considerations” would be more appropriate?

> +** 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.
> +
> +Of course, group decision-making processes are difficult to manage.
> +
> +The ease of commenting may bring a slightly diminished signal-to-noise ratio
> +in collected feedback, particularly on easily bike-shedded topics.
> +
> +** Open questions
> +
> +There are still questions regarding the desired scope of the process.  While
> +we want to ensure that changes which affect the 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.
> +
> +* Unresolved questions

I think these two sections in the context of this foundational document
look a bit ridiculous.  :-)  But maybe that’s okay?

Thanks!

Ludo’.