[bug#74736,v2,1/1] rfc: Add Request-For-Comment process.

  From: Simon Tournier <zimon.toutoune@gmail.com>

* rfc/0001-rfc-process.txt: New file.
* rfc/0000-template.txt: New file.

Co-authored-by: Noé Lopez <noe@xn--no-cja.eu>
Change-Id: Ide88e70dc785ab954ccb42fb043625db12191208
---
 rfc/0000-template.txt    |  76 +++++++++++++
 rfc/0001-rfc-process.txt | 232 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 308 insertions(+)
 create mode 100644 rfc/0000-template.txt
 create mode 100644 rfc/0001-rfc-process.txt
  

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 <noe@noé.eu> 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 guix-patches@gnu.org
> +  5. Announce your RFC to guix-devel@gnu.org
> +
> +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’.
  

Hi all,

Thanks Noé!  I added you as co-supporter; someone definitively
required. ;-)

Thanks Steve for reaching me some weeks end ago.

Well, based on Noé’s v2, I polished some comments and sent v3; based on
what my follow up started weeks (months?) ago.


On Thu, 12 Dec 2024 at 19:14, Ludovic Courtès <ludo@gnu.org> wrote:

> 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…”?

I think it helps to understand.  Concrete examples always help, IMHO.

Therefore, I propose what your wording.  Then, past examples where this
RFC process would have been helpful, I guess.

>> +  1. Clone https://git.savannah.gnu.org/git/guix.git
>
> I would suggest a separate repo.

Bah since we are putting all there… When you see etc/ ;-)


>> +** Decision making: consensus
>
> … and drop this.

I think it makes more sense to have the Decision Making as RFC and then
the manual refers to it, and not the converse. ;-)

Therefore, I would keep the section here.  And once we are done, letting
the manual as-is, I would link to RFC.

What defines the Decision Making *is* RFC and not the manual. ;-)


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

I’ve drop this “RFC teams“ or “RFC editors” because in my initial idea,
this is the aim of “co-supporter(s)”.  See the relevant section; does it
need to be improved?


>> +** Backward Compatibility
>> +
>> +None.
>> +
>> +** Forward compatibility
>
> I’m not sure what’s expected in these sections.  Maybe “Compatibility
> Considerations” would be more appropriate?

Yes, maybe “Compatibility Consideration”.  It needs to be in agreement
with the template.

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

I think that the first RFC must respects what it asks to other RFC. ;-)

And if the consensus is not reached, we need a place to summarize the
unresolved discussion, no?


Again, thanks Noé and Steve for taking care of that!

Cheers,
simon
  

Hi,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

>>> +** Decision making: consensus
>>
>> … and drop this.
>
> I think it makes more sense to have the Decision Making as RFC and then
> the manual refers to it, and not the converse. ;-)
>
> Therefore, I would keep the section here.  And once we are done, letting
> the manual as-is, I would link to RFC.
>
> What defines the Decision Making *is* RFC and not the manual. ;-)

Earlier, I wrote:

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

Since (1) day-to-day contributions do not follow the RFC process and (2)
teams and consensus-based decision making are already defined (and went
through peer review), I think it makes more sense to build on these two
sections we already have.

>>> +* Unresolved questions
>>
>> I think these two sections in the context of this foundational document
>> look a bit ridiculous.  :-)  But maybe that’s okay?
>
> I think that the first RFC must respects what it asks to other RFC. ;-)
>
> And if the consensus is not reached, we need a place to summarize the
> unresolved discussion, no?

I already mentioned it back in February, FWIW:
<https://issues.guix.gnu.org/66844#3-lineno186>.

Anyway, no big deal, but it will certainly look strange eventually.

Ludo’.
  

Hi Ludo,

I agree (more than less) with all the other comments except this
one. :-)


>>>> +** Decision making: consensus
>>>
>>> … and drop this.
>>
>> I think it makes more sense to have the Decision Making as RFC and then
>> the manual refers to it, and not the converse. ;-)
>>
>> Therefore, I would keep the section here.  And once we are done, letting
>> the manual as-is, I would link to RFC.
>>
>> What defines the Decision Making *is* RFC and not the manual. ;-)
>
> Earlier, I wrote:
>
>> 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.
>
> Since (1) day-to-day contributions do not follow the RFC process and (2)
> teams and consensus-based decision making are already defined (and went
> through peer review), I think it makes more sense to build on these two
> sections we already have.

I still think the RFC process must contain its own “Decision Making”
process and must not refer to external parts that could be changed
without going via this RFC process.

Somehow, from my point of view, it makes more sense to encode “Decision
Making” or “Commit Access” or “Teams” via future RFCs than via sections
in the manual.  And we need to bootstrap the “Decision Making”, no?

For sure, I agree that we do not build from nothing.  To me, this very
first RFC makes explicit the structure we already have.  Maybe I
misunderstand something, IMHO, we should avoid the temptation to say:
Hey we already have a way to collaborate thus let implicitly rely on.

Hum? 🤔 Somehow, I would find the RFC process incomplete without an
explicit self-contained “Decision Making” section.

What do you think?  What do people think?

Cheers,
simon
  

Hi,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

>> Since (1) day-to-day contributions do not follow the RFC process and (2)
>> teams and consensus-based decision making are already defined (and went
>> through peer review), I think it makes more sense to build on these two
>> sections we already have.
>
> I still think the RFC process must contain its own “Decision Making”
> process and must not refer to external parts that could be changed
> without going via this RFC process.
>
> Somehow, from my point of view, it makes more sense to encode “Decision
> Making” or “Commit Access” or “Teams” via future RFCs than via sections
> in the manual.  And we need to bootstrap the “Decision Making”, no?

I agree that sections in the manual are suboptimal.  That is why I
proposed moving contributing.texi to a document of its own, which would
sit next to the RFC process document.  I don’t consider it a
prerequisite though.

> For sure, I agree that we do not build from nothing.  To me, this very
> first RFC makes explicit the structure we already have.  Maybe I
> misunderstand something, IMHO, we should avoid the temptation to say:
> Hey we already have a way to collaborate thus let implicitly rely on.
>
> Hum? 🤔 Somehow, I would find the RFC process incomplete without an
> explicit self-contained “Decision Making” section.

What I’d like to stress is that decision making also happens outside the
RFC process; not everything will go through the RFC process.  So we’ll
need to have that manual section for day-to-day contributions anyway.

But yeah, maybe we can have one specific to the RFC document, too.

Ludo’.