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

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