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

From: Simon Tournier <[email-masked]>
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 <[email-masked]>
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 [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 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