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

Message #5 received at submit@debbugs.gnu.org (full text, mbox, reply):

From: Noé Lopez <noe@xn--no-cja.eu>

To: guix-patches@gnu.org

Cc: Noé Lopez <noelopez@free.fr>

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

Date: Sun, 8 Dec 2024 13:29:52 +0100

From: Noé Lopez <noelopez@free.fr>

Hi,

It has been more than a year since Simon Tournier’s original patch[1] for
specifying a “request for comment” process.  I believe that such a process can
pave the way for big changes to make their way to Guix and the establishment
of a governance model, among other things.

Therefore, I have taken it upon myself to produce an updated version taking
into account the comments received on the original patch and my own changes.

These changes are targeted not only to committers, but to every contributor so
that anyone can propose important changes.  So anyone should feel free to
comment what they think :)

Have a good day,
Noé Lopez

[1] https://issues.guix.gnu.org/66844

Simon Tournier (1):
  rfc: Add Request-For-Comment process.

 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


base-commit: 1affd2b5aa7f5467a44cf757c4fc0c6956d3f3c9
-- 
2.46.0

Message #8 received at 74736@debbugs.gnu.org (full text, mbox, reply):

From: Noé Lopez <noe@xn--no-cja.eu>

To: 74736@debbugs.gnu.org

Cc: Noé Lopez <noe@xn--no-cja.eu>

Subject: [PATCH v2 1/1] rfc: Add Request-For-Comment process.

Date: Sun, 8 Dec 2024 13:31:43 +0100

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

diff --git a/rfc/0000-template.txt b/rfc/0000-template.txt
new file mode 100644
index 0000000000..8c4077e753
--- /dev/null
+++ b/rfc/0000-template.txt
@@ -0,0 +1,76 @@
+# -*- mode:org -*-
+#+TITLE: <The meaningful name of the proposal>
+#+DATE: <date when the process starts>
+
++ Issue: <number assigned by Debbugs>
++ Status: <pending|done|unsuccessful|deprecated>
++ Supporter: <Your Name>
++ Co-supporter(s): <Some> <Names>
+
+* Summary
+
+A one-paragraph explanation.  Main sales pitch.
+
+* Motivation
+
+Describe the problem·s this RFC attempts to address as clearly as possible and
+optionally give an example.  Explain how the status quo is insufficient or not
+ideal.
+
+* Detail design
+
+Main part.  The sections answers What are the tradeoffs of this proposal
+compared to status quo or potential alternatives?  Explain details, corner
+cases, provide examples.  Explain it so that someone familiar can understand.
+
+It is best to exemplify, contrived example too. If the Motivation section
+describes something that is hard to do without this proposal, this is a good
+place to show how easy that thing is to do with the proposal.
+
+**  Backward compatibility
+
+# Christopher Baines:
+# I'm struggling to think of exactly how backwards compatibility would
+# apply to potential RFCs for Guix.
+
+Will your proposed change cause a behaviour change?  Assess the expected
+impact on existing code on the following scale:
+
+0. No breakage
+1. Breakage only in extremely rare cases (exotic or unknown cases)
+2. Breakage in rare cases (user living in cutting-edge)
+3. Breakage in common cases
+
+Explain why the benefits of the change outweigh the costs of breakage.
+Describe the migration path.  Consider specifying a compatibility warning for
+one or more releases.  Give examples of error that will be reported for
+previously-working cases; do they make it easy for users to understand what
+needs to change and why?
+
+The aim is to explicitely consider beforehand potential Backward Compatibility
+issue.
+
+** Forward compatibility
+
+# Christopher Baines:
+# I do think it's worth explicitly bringing up something like the "cost of
+# reverting". That is, it's important to discuss things more if there's a
+# high cost to changing the approach later. For these "high cost of later
+# change" situations, the RFC process will probably be particularly
+# valuable.
+
+# Noé Lopez:
+# I think this section could apply very well to governance proposals.
+
+How will your proposed change evolve with time?  What is the cost of changing
+the approach later?
+
+* Unresolved questions
+
+Explicitly list any remaining issues.  At submitting time, be upfront and
+trust that the community will help.  At reviewing time, this section tracks
+the details about the status of the process.
+
+At the end of the process, this section will be empty.  If not, please be
+explicit with the known issues by adding a dedicated subsection under Detail
+design.
diff --git a/rfc/0001-rfc-process.txt b/rfc/0001-rfc-process.txt
new file mode 100644
index 0000000000..4282e84230
--- /dev/null
+++ b/rfc/0001-rfc-process.txt
@@ -0,0 +1,232 @@
+# -*- mode:org -*-
+#+TITLE: Request-For-Comment process
+#+DATE: 2023-10-31
+
++ Issue: 66844
++ Status: pending
++ Supporter: Simon Tournier
++ Co-supporters:
+
+* Summary
+
+The "RFC" (request for comments) process is intended to provide a consistent
+and structured path for major changes and features to enter the Guix project,
+so that all stakeholders can make decisions collectively and be confident
+about the direction it is evolving in.
+
+* 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.  This is a proposal for a more principled
+RFC process to make it a more integral part of the overall development
+process, and one that is followed consistently to introduce substantial
+features.
+
+There are a number of changes that are significant enough that they could
+benefit from wider community consensus before being introduced.  Either
+because they introduce new concepts, big changes or are controversial enough
+that not everybody will consent on the direction to take.
+
+Therefore, the purpose of this RFC is to introduce a process that allows to
+bring the discussion upfront and strengthen decisions.  This RFC is used to
+bootstrap the process and further RFCs can be used to refine the process.
+
+Note that this process does not cover most of the changes.  It covers
+significant changes, for some examples:
+
+ + 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)
+
+* Detail design
+
+** When you need 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
+
+A patch submission to Debbugs that contains any of the afore-mentioned
+substantial changes may be asked to first submit a RFC.
+
+** How the process works
+
+  1. Clone https://git.savannah.gnu.org/git/guix.git
+  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
+idea for implementing it.  If an implementation is attached to the detailed
+design, it might help the discussion.
+
+At this point, at least one other person must volunteer to be "co-supporter".
+The aim is to improve the chances that the RFC is both desired and likely to
+be implemented.
+
+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.
+
+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.
+
+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.
+
+An unsuccessful RFC is *not* a judgment on the value of the work, so a refusal
+should rather be interpreted as “let’s discuss again with a different angle”.
+The last state of an unsuccessful RFC is archived under the directory
+rfc/withdrawn/.
+
+** Co-supporter
+
+A co-supporter is a contributor sufficiently familiar with the project’s
+practices, hence it is recommended, but not mandatory, to be a contributor
+with commit access.  The co-supporter helps the supporter, they are both
+charged with keeping the proposal moving through the process.  The
+co-supporter role is to help the proposal supporter by being the timekeeper
+and helps in pushing forward until process completion.
+
+The co-supporter doesn't necessarily 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.
+
+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.
+
+** Timeline
+
+The lifetime of an RFC is structured into the following periods:
+  submission (7d) ⟶ comments (30–60d) ⟶ last call (14d) ⟶ withdrawn OR final
+
+*** Submission
+
+The author submits their proposal to the patches mailing list and the RFC team
+which will read the proposal and can advise the author on improving their RFC.
+This first round of review is provided only to help the author and should not
+reflect personal bias or opinions.
+
+If seven days have passed without answer or the author thinks that his
+RFC is ready then he may move on to the comment period.
+
+*** Comment
+
+The author publishes their RFC to guix-devel and starts a discussion period of
+at least 30 days.  It is up to the supporter and co-supporter to ensure that
+sufficient discussion is solicited. Make sure that all have the time for
+expressing their comments.  The proposal is about significant changes, thus
+more time is better than less.
+
+The author is encouraged to publish updated versions of their RFC at any point
+during the discussion period.
+
+Once the discussion goes stale or after 60 days, the author should publish or
+keep their final version and move into the last call period.
+
+*** 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
+in less than six months.
+
+If no consensus can be reached or the changes were not applied in less than
+six months, the RFC becomes withdrawn and is archived.  The author may also
+withdraw their RFC at any point.
+
+** Decision making: consensus
+
+It is expected from all contributors, and even more so from committers, to
+help build consensus and make decisions based on consensus.  By using
+consensus, we are committed to finding solutions that everyone can live with.
+
+It implies that no decision is made against significant concerns and these
+concerns are actively resolved with proposals that work for everyone.  A
+contributor, without or with commit access, wishing to block a proposal bears
+a special responsibility for finding alternatives, proposing ideas/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 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.
+
+** Template of RFC
+
+# Ludovic Courtès:
+# I’d go for one format, preferably Markdown because we have a library to
+# parse it.
+
+The structure of the RFC is captured by the template; see the file
+rfc/0000-template.txt.  It is recommended to write using markup language as,
+for example, Org-mode or Markdown or reStructuredText.
+
+** Backward Compatibility
+
+None.
+
+** Forward compatibility
+
+The RFC process can be refined by further 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.
+
+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
-- 
2.46.0

Message #11 received at 74736@debbugs.gnu.org (full text, mbox, reply):

From: "Artyom V. Poptsov" <poptsov.artyom@gmail.com>

To: 74736@debbugs.gnu.org

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

Date: Mon, 09 Dec 2024 23:47:18 +0300

[Message part 1 (text/plain, inline)]

Hello Noé Lopez,

thanks for pushing this idea forward!  I think that the RFC process will
help to track all the major initiatives in GNU Guix -- present and
future ones.

I know that there are several long-term big projects inside Guix, namely
Guile daemon, distributed substitutes and maybe more.  In my view the
problem is that the information about those projects is buried in the
Git branches and E-Mail discussions.  Maybe RFCs in the well-known place
inside the repository will help developers to see what the community at
large is up to.

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

To my taste, as for Emacs user, the plain old org-mode format is good
enough to write RFCs, but that's no more than a preference.  Many people
using Markdown nowadays so maybe it will help to make the RFC process
more friendly for newcomers.

- avp

-- 
Artyom "avp" Poptsov <poptsov.artyom@gmail.com>
Home page: https://memory-heap.org/~avp/
CADR Hackerspace co-founder: https://cadrspace.ru/
GPG: D0C2 EAC1 3310 822D 98DE  B57C E9C5 A2D9 0898 A02F

[signature.asc (application/pgp-signature, inline)]

Message #18 received at 74736@debbugs.gnu.org (full text, mbox, reply):

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

To: Noé Lopez <noe@xn--no-cja.eu>

Cc: 74736@debbugs.gnu.org, Christopher Baines <mail@cbanes.net>, Simon Tournier <zimon.toutoune@gmail.com>

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

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

Message #21 received at 74736@debbugs.gnu.org (full text, mbox, reply):

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

To: 74736@debbugs.gnu.org

Cc: Noé Lopez <noe@xn--no-cja.eu>, Noé Lopez <noelopez@free.fr>, Ludovic Courtès <ludo@gnu.org>, Christopher Baines <mail@cbanes.net>, Simon Tournier <zimon.toutoune@gmail.com>

Subject: [PATCH v3] rfc: Add Request-For-Comment process.

Date: Thu, 12 Dec 2024 20:30:56 +0100

* 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 | 248 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 324 insertions(+)
 create mode 100644 rfc/0000-template.txt
 create mode 100644 rfc/0001-rfc-process.txt

diff --git a/rfc/0000-template.txt b/rfc/0000-template.txt
new file mode 100644
index 0000000000..8c4077e753
--- /dev/null
+++ b/rfc/0000-template.txt
@@ -0,0 +1,76 @@
+# -*- mode:org -*-
+#+TITLE: <The meaningful name of the proposal>
+#+DATE: <date when the process starts>
+
++ Issue: <number assigned by Debbugs>
++ Status: <pending|done|unsuccessful|deprecated>
++ Supporter: <Your Name>
++ Co-supporter(s): <Some> <Names>
+
+* Summary
+
+A one-paragraph explanation.  Main sales pitch.
+
+* Motivation
+
+Describe the problem·s this RFC attempts to address as clearly as possible and
+optionally give an example.  Explain how the status quo is insufficient or not
+ideal.
+
+* Detail design
+
+Main part.  The sections answers What are the tradeoffs of this proposal
+compared to status quo or potential alternatives?  Explain details, corner
+cases, provide examples.  Explain it so that someone familiar can understand.
+
+It is best to exemplify, contrived example too. If the Motivation section
+describes something that is hard to do without this proposal, this is a good
+place to show how easy that thing is to do with the proposal.
+
+**  Backward compatibility
+
+# Christopher Baines:
+# I'm struggling to think of exactly how backwards compatibility would
+# apply to potential RFCs for Guix.
+
+Will your proposed change cause a behaviour change?  Assess the expected
+impact on existing code on the following scale:
+
+0. No breakage
+1. Breakage only in extremely rare cases (exotic or unknown cases)
+2. Breakage in rare cases (user living in cutting-edge)
+3. Breakage in common cases
+
+Explain why the benefits of the change outweigh the costs of breakage.
+Describe the migration path.  Consider specifying a compatibility warning for
+one or more releases.  Give examples of error that will be reported for
+previously-working cases; do they make it easy for users to understand what
+needs to change and why?
+
+The aim is to explicitely consider beforehand potential Backward Compatibility
+issue.
+
+** Forward compatibility
+
+# Christopher Baines:
+# I do think it's worth explicitly bringing up something like the "cost of
+# reverting". That is, it's important to discuss things more if there's a
+# high cost to changing the approach later. For these "high cost of later
+# change" situations, the RFC process will probably be particularly
+# valuable.
+
+# Noé Lopez:
+# I think this section could apply very well to governance proposals.
+
+How will your proposed change evolve with time?  What is the cost of changing
+the approach later?
+
+* Unresolved questions
+
+Explicitly list any remaining issues.  At submitting time, be upfront and
+trust that the community will help.  At reviewing time, this section tracks
+the details about the status of the process.
+
+At the end of the process, this section will be empty.  If not, please be
+explicit with the known issues by adding a dedicated subsection under Detail
+design.
diff --git a/rfc/0001-rfc-process.txt b/rfc/0001-rfc-process.txt
new file mode 100644
index 0000000000..52d851f879
--- /dev/null
+++ b/rfc/0001-rfc-process.txt
@@ -0,0 +1,248 @@
+# -*- mode:org -*-
+#+TITLE: Request-For-Comment process
+#+DATE: 2023-10-31
+
++ Issue: 66844
++ Status: pending
++ Supporter: Simon Tournier
++ Co-supporters: Noé Lopez
+
+* Summary
+
+The "RFC" (request for comments) process is intended to provide a consistent
+and structured path for major changes and features to enter the Guix project,
+so that all stakeholders can make decisions collectively and be confident
+about the direction it is evolving in.
+
+* 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, lack of a central place to consult
+contributors and users, and lack of clear deadlines.  This is a proposal for a
+more principled RFC process to make it a more integral part of the overall
+development process, and one that is followed consistently to introduce
+substantial features.
+
+There are a number of changes that are significant enough that they could
+benefit from wider community consensus before being introduced.  Either
+because they introduce new concepts, big changes or are controversial enough
+that not everybody will consent on the direction to take.
+
+Therefore, the purpose of this RFC is to introduce a process that allows to
+bring the discussion upfront and strengthen decisions.  This RFC is used to
+bootstrap the process and further RFCs can be used to refine the process.
+
+It covers 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:
+
+  - 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.)
+
+For concrete past examples where this RFC process would be helpful:
+
+ - Removing input labels from package definitions, #49169
+ - Add 'guix shell' to subsume 'guix environment', #50960
+ + Trustable "guix pull", #22883
+ + Add "Deprecation Policy", #72840
+ + Collaboration via team and branch-features, several places over all the
+   mailing lists.
+
+* Detailed Design
+
+** When To Follow This Trocess
+
+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
+
+For general day-to-day contributions, please follow the regular process as
+described by manual sections "Submitting Patches", "Reviewing the Work of
+Others", "Teams" and "Making Decisions".
+
+A patch submission that contains any of the aforementioned substantial changes
+may be asked to first submit a RFC.
+
+** How the process works
+
+  1. Clone https://git.savannah.gnu.org/git/guix.git
+  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 is ecommended to have an idea for
+implementing it.  If an implementation is attached to the detailed design, it
+might help the discussion.
+
+At this point, at least one other person must volunteer to be "co-supporter".
+The aim is to improve the chances that the RFC is both desired and likely to
+be implemented.
+
+Once supporter and co-supporter(s) are committed in the RFC process, the
+review discussion starts.  Publicizing of the RFC on the project's mailing
+list named guix-devel is mandatory, and on other main communication channels
+is highly recommended.
+
+After a number of rounds of review, the discussion should settle and a general
+consensus should emerge.  Please follow the "Decision Process" and "Timeline"
+sections.
+
+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
+participants have agreed to the feature and are amenable to merging it.
+
+An unsuccessful RFC is *not* a judgment on the value of the work, so a refusal
+should rather be interpreted as “let’s discuss again with a different angle”.
+The last state of an unsuccessful RFC is archived under the directory
+rfc/withdrawn/.
+
+** Co-supporter
+
+A co-supporter is a contributor sufficiently familiar with the project’s
+practices, hence it is recommended, but not mandatory, to be a contributor
+with commit access.  The co-supporter helps the supporter, they are both
+charged with keeping the proposal moving through the process.  The
+co-supporter role is to help the proposal supporter by being the timekeeper
+and helps in pushing forward until process completion.
+
+The co-supporter doesn't necessarily 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.
+
+** Timeline
+
+The lifetime of an RFC is structured into the following recommended periods:
+
+  submission (7d) ⟶ comments (30–60d) ⟶ last call (14d) ⟶ withdrawn OR final
+
+The author may withdraw their RFC proposal at any time; and it might be
+submitted again.
+
+*** Submission (up to 7 days)
+
+The author submits their RFC proposal as a regular patch and look for
+co-supporter(s). See 'Co-supporter' section.
+
+Once the RFC is co-supported, it marks the start of a discussion period.
+
+*** Comment (at least 30 days, up to 60 days)
+
+The comment period starts once the author publishes their RFC to guix-devel,
+then the proposal is freely discussed for a period of at least 30 days.  It is
+up to the supporter and co-supporter(s) to ensure that sufficient discussion
+is solicited.  Please make sure that all have the time and space for
+expressing their comments.  The proposal is about significant changes, thus
+more opinions is better than less.
+
+The author is encouraged to publish updated versions of their RFC at any point
+during the discussion period.
+
+Once the discussion goes stale or after 60 days, the author must summarize the
+state of the conversation and keep the final version.
+
+It moves to the last call period.
+
+*** Last call (up to 14 days)
+
+The author publishes a final version of the RFC and a last grace period of 14
+days is granted.  People are asked to agree or disagree by commenting:
+
+ - +1 / LGTM: I support
+ - =0 / LGTM: I will live with it
+ - -1: I disagree with this proposal
+
+At least half of people with commit acces must express their voice with the
+keys above during this last call.  We need to be sure that the RFC had been
+read by people committed to take care of the project, since it proposes an
+important change.
+
+When a positive consensus is reached, the RFC becomes effective.  If not, the
+proposal is archived and the statu quo continues.
+
+
+** Decision Making: consensus
+
+It is expected from all contributors, and even more so from committers, to
+help build consensus and make decisions based on consensus.  By using
+consensus, we are committed to finding solutions that everyone can live with.
+
+It implies that no decision is made against significant concerns and these
+concerns are actively resolved with proposals that work for everyone.  A
+contributor, without or with commit access, wishing to block a proposal bears
+a special responsibility for finding alternatives, proposing ideas/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 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.
+
+** Template of RFC
+
+The structure of the RFC is captured by the template; see the file
+rfc/0000-template.txt.  Please use Markdown as markup language.
+
+** Backward Compatibility
+
+None.
+
+** Forward compatibility
+
+The RFC process can be refined by further 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.
+
+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

base-commit: 93e1586116f39a30ba1fcb67bd839a43533dfaf4
-- 
2.45.2

Message #24 received at 74736@debbugs.gnu.org (full text, mbox, reply):

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

To: Ludovic Courtès <ludo@gnu.org>, Noé Lopez <noe@xn--no-cja.eu>

Cc: 74736@debbugs.gnu.org, Christopher Baines <mail@cbanes.net>, Steve George <steve@futurile.net>

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

Date: Thu, 12 Dec 2024 20:47:17 +0100

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

Message #27 received at 74736@debbugs.gnu.org (full text, mbox, reply):

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

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

Cc: Noé Lopez <noe@xn--no-cja.eu>, 74736@debbugs.gnu.org, Christopher Baines <mail@cbanes.net>, Steve George <steve@futurile.net>

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

Date: Sat, 14 Dec 2024 11:06:15 +0100

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

Message #30 received at 74736@debbugs.gnu.org (full text, mbox, reply):

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

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

Cc: Noé Lopez <noe@xn--no-cja.eu>, Noé Lopez <noelopez@free.fr>, 74736@debbugs.gnu.org, Christopher Baines <mail@cbanes.net>

Subject: Re: [bug#74736] [PATCH v3] rfc: Add Request-For-Comment process.

Date: Sat, 14 Dec 2024 11:47:19 +0100

Thanks for v3!

Some of my more superficial comments earlier this week remain
unaddressed:

  • I think it should be Markdown, and in a separate repo.

  • There are too many explicit references to Debbugs, which I think is
    not future-proof.

I think the text itself needs more work to address and remove remaining
comments that appear in the body, to improve grammar and wording, and to
make it shorter (it’s way too long IMO).  But that can come in a second
phase.

Questions/comments about the process that I overlooked before:

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

This diagram doesn’t show everything I think; for example…

> +*** Submission (up to 7 days)
> +
> +The author submits their RFC proposal as a regular patch and look for
> +co-supporter(s). See 'Co-supporter' section.
> +
> +Once the RFC is co-supported, it marks the start of a discussion period.

… what happens when the submitter doesn’t find supporters in that
period? I’m guessing the RFC goes in “withdrawn” state?

The diagram should reflect that, and we can render it with Dot.

> +*** Last call (up to 14 days)
> +
> +The author publishes a final version of the RFC and a last grace period of 14
> +days is granted.  People are asked to agree or disagree by commenting:
> +
> + - +1 / LGTM: I support
> + - =0 / LGTM: I will live with it
> + - -1: I disagree with this proposal
> +
> +At least half of people with commit acces must express their voice with the
> +keys above during this last call.  We need to be sure that the RFC had been
> +read by people committed to take care of the project, since it proposes an
> +important change.

I think committers here are mentioned as a simple way to express
membership and avoid infiltration, but it has the downside of ignoring
many members and giving committers a special privilege.

I propose this definition: anyone who is on a team (in ‘teams.scm’) is a
voting member*.

We can keep a quorum, but I think 50% of the voters is too ambitious;
maybe 25%?

This would become¹:

  Once the final version is published, team members have 14 days to cast
  one of the following votes about the RFC:

    - Support (+1);
    - Accept (0);
    - Reject (-2).

  Votes are cast by replying on the patch-tracking entry of the RFC.

  The RFC is accepted if (1) at least 25% of the voting members cast a
  vote, and (2) the sum of votes is non-negative.  In other cases, the
  RFC is withdrawn.

Thoughts?

Ludo’.


* We’ll have to create new teams and update them so we don’t forget
  anyone, notably translators, sysadmins, graphics designers, and so on.

¹ Inspired by
  <https://codeberg.org/mergiraf/mergiraf/src/branch/main/GOVERNANCE.md>.

Send a report that this bug log contains spam.