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

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

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