# -*- 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