[bug#66844] [PATCH] rfc: Add Request-For-Comment process.

[Ludovic Courtès]

Hello!

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

> --- /dev/null
> +++ b/rfc/0001-rfc-process.txt
> @@ -0,0 +1,180 @@
> +# -*- 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 controlled path for new features to enter the Guix project, so that all
> +stakeholders can be confident about the direction it is evolving in.
> +
> +* Motivation
> +
> +The freewheeling way that we add new features to Guix has been good for early
> +development, but for Guix to become a broadly used system we need to develop
> +some more self-discipline when it comes to changing our beloved system.  This

I agree with the spirit but I’m happy to propose wording changes once
there’s consensus on the general direction (for example, I think
“freewheeling”, “beloved”, and “self-discipline” are too casual and/or
demeaning for such a document).

> +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 agree on the direction to take.

I think it’s about community input and consent (as opposed to “everybody
will agree”).

> +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)
> + + massive Python 2 removal
> +   (Merging the purge-python2-packages branch, mailing list guix-devel)
> + + collaboration via team and branch-features
> +   (several places mailing list guix-devel)

I mostly agree with Chris’s comments here.

> +* 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.

I think we should be explicit about whether only code is subject to RFCs
or whether non-code matters may also be subject to RFCs: processes and
governance, documentation, web site, l10n workflow, Outreachy/GSoC
internship management, etc.

I don’t have an opinion yet on whether that should be the case for all
of these topics, though my initial impression is that it would work well
for the documentation and web site for instance.

> +  + Any change that modifies Guix API

We’ll have to be clearer here because there many interfaces in Guix.
There’s the command-line interface, and there are Scheme interfaces.

The latter is split into rather different categories: user-facing
modules (those one uses from a manifest, from a Home/System config, or
from a package module), package and service modules, modules external
libraries and tool may rely on ((guix store), (guix packages), (guix
derivations), etc.), and the large family of modules that are mostly
used internally ((guix cpio), (guix docker), (guix cve), …).

The expectations are different here: we’re probably much less strict for
the last category than we are for the first ones.

So, as an attempt to capture that, I would at least word it along these
lines:

  Changes that modify user-facing interfaces: command-line interfaces
  and core Scheme interfaces that external libraries and programs may
  rely on.

> +  + Big restructuring of packages

Wouldn’t this overlap with teams?

For example, I would expect the Python team to be responsible for
Python-wide changes, but then I agree that it would be nice to have
representatives from other teams (maybe ‘core-packages’?) be in the loop
for wide-ranging changes.

> +  + Introduction or removal of subcommands

Might be covered with wording as shown above.

> +Certain changes do not require an RFC:
> +
> +  - Adding, updating packages, removing outdated packages
> +  - Fixing security updates and bugs that don't break interfaces

At first sight one might get the feeling that few changes are exempt
from RFCs; we should instead clarify that this is the opposite.

Chris’ idea of expressing RFC-worthiness in terms of “cost of reverting”
or cost of eventually changing our minds better captures the intent.

> +** Comment period
> +
> +It is up to the supporter and co-supporter to ensure that sufficient
> +discussion is solicited.  Let two weeks for people to comment is a good
> +average.  Make sure that all have the time for expressing their comments.  
> The
> +proposal is about significant changes, thus more time is better than less.

Terminology: what about “proponent” (the person who writes the proposal
and takes responsibility for pushing it forward) and “supporters” (there
could be several of them)?

I think we need a clear automaton here:

  submitted --(7d)--> draft --(30d–60d)--> withdrawn | final

Meaning that: the initial patch (sent to guix-patches) would be applied
or rejected by an “RFC editor” (?) within 7 days, the comment period
would be at least 30 days and at most 60 days, and after the comment
period the proposal would move either to “withdrawn” state (meaning more
discussion is needed and/or consensus could not be achieved and/or
proponent gave up) or to “final” state (proponent and others may submit
patches implementing what they proposed within say 6 months following
approval).

Of course we can tweak these details but anyhow the automaton and
timeline should be clear.

I took inspiration from:

  https://srfi.schemers.org/srfi-process.html

> +** Merging the outcome
> +
> +Whoever merges the successful RFC should do the following:

It’s unclear to me what “merging the RFC” mean.  Presumably the text
itself was merged from the start.

> +** Template of RFC
> +
> +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.

I’d go for one format, preferably Markdown because we have a library to
parse it.

> +** 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 don’t think this belongs here.  I’m also not sure the RFC process
document has to follow the RFC template: it looks nice to our nerd
minds, but it might be unhelpful.

I’ll leave out the template for now.

Ludo’.