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

* rfc/0001-rfc-process.txt: New file.
* rfc/0000-template.txt: New file.

Change-Id: Ide88e70dc785ab954ccb42fb043625db12191208
---
 rfc/0000-template.txt    |  58 +++++++++++++
 rfc/0001-rfc-process.txt | 180 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 238 insertions(+)
 create mode 100644 rfc/0000-template.txt
 create mode 100644 rfc/0001-rfc-process.txt


base-commit: c0895371c5759c7d9edb330774e90f192cc4cf2c

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

> * rfc/0001-rfc-process.txt: New file.
> * rfc/0000-template.txt: New file.
>
> Change-Id: Ide88e70dc785ab954ccb42fb043625db12191208
> ---
>  rfc/0000-template.txt    |  58 +++++++++++++
>  rfc/0001-rfc-process.txt | 180 +++++++++++++++++++++++++++++++++++++++
>  2 files changed, 238 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..22dca35a56
> --- /dev/null
> +++ b/rfc/0000-template.txt
> @@ -0,0 +1,58 @@
> +# -*- 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>
> +

Thanks for writing this up Simon.

Some bikeshedding over the specific words and phrases follows, but I've
also got a few actual changes to suggest.

Generally I think this is something to try, I think the key issues to
address are around what is suitable for an RFC, and including some
checkpoints in the structure to encourage the discussion along and
identify when it's no longer progressing.

> +* Summary
> +
> +A one-paragraph explanation.  Main sales pitch.

I'm not sure a summary is needed, or maybe it should just be a single
sentence summary. I think the Motivation section may end up just
repeating most of this and is a more useful thing to read first.

> +* Motivation
> +
> +Describe the use case as clearly as possible and optionally give an example.
> +Explain how the status quo is insufficient or not ideal.  This section answers
> +Why is this proposal a good idea?  Why is it worth the effort to discuss and
> +implement such?

I'd maybe say "Describe the problem(s) this RFC attempts to address, and
how it might do this". I'm also not sure we need the last sentence,
although maybe it would be good to have a paragraph specifically on what
makes this suitable for an RFC.

> +* Detail design
> +
> +Main part.  The sections answers What is the cost of this proposal compared to
> +status quo or potential alternatives?  Explain details, corner cases, provide
> +examples.  Explain it so that someone familiar can understand.

Maybe tradeoffs would be a better word to use rather than cost, so "What
are the tradeoffs of this proposal compared ...".

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

I'm struggling to think of exactly how backwards compatibility would
apply to potential RFCs for Guix.

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.

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

Maybe "structured" rather than "controlled".

I also think this should be more general than new features. To me this
is about making decisions collectively.

For example, an RFC might be about controlling scope or doing some key
refactoring rather than adding new features.

> +* 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
> +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 substancial 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 agree 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)

I think this is a good example, again, I think we shouldn't just limit
RFCs for new features and this is an example of something that isn't a
new feature.

I think the RFC process would have been useful because there's a high
cost in doing this refactoring and in undoing it if something goes
wrong.

> + + introduction of =guix shell= and deprecation of =guix environment=
> +   (Add 'guix shell' to subsume 'guix environment', #50960)

Maybe an RFC could be useful here since removing or changing the shell
command after it's added would be difficult.

> + + introduction of authentication mechanism (Trustable "guix pull", #22883)

This does seem suitable of an RFC because of the complexity of fixing
issues after it's introduced.

> + + massive Python 2 removal
> +   (Merging the purge-python2-packages branch, mailing list guix-devel)

Adding Python 2 back doesn't seem difficult, so I'm not sure this would
benefit from being discussed as a specific RFC.

Maybe you could have an RFC about the policy for keeping software around
in Guix, and then the structured RFC process would help the discussion,
but I don't think it's useful for specific issues like this.

> + + collaboration via team and branch-features
> +   (several places mailing list guix-devel)

Like above, because this is a discussion about process, I think the RFC
process could provide structure, and authority to the decision made.

I think generally I think the RFC process is useful when the decisions
are hard/costly to revert and/or for cases where the discussion benefits
from the structure and authority that the RFC process can provide.

> +* 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.
> +
> +  + Any change that modifies Guix API

The key thing in my mind is changes that are hard to revert. Some API
changes may be hard to revert, but some could be very minor (e.g. making
a existing procedure public).

> +  + Big restructuring of packages
> +  + Introduction or removal of subcommands

I guess this would normally mean a hard to revert change.

> +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
> +
> +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 is recommended.

Having made a few changes to Guix's API over the years (e.g. adding
narinfo stuff to the API #45409) I think we maybe need to provide a
backstop for requiring supporters.

There's plenty of useful but boring API changes that have happened, and
probably will happen in the future, and we maybe need to set out that
there's some group of people (maybe committers) which will be
co-supporters if there's not anyone volunteering.

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

I think we should specify a time period (say 3 weeks) where the proposer
needs to send out an update saying what the state is, and there should
be a requirement that the discussion has progressed since the previous
update. If the discussion is no longer progressing, it's time to
reject/accept/pause or do something else with the RFC.

> +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
> +rfcs/unsuccessful/.
> +
> +** 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.
> +
> +** 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.
> +
> +** 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
> +
> +Whoever merges the successful RFC should do the following:
> +
> + 1. Fill in the remaining metadata in the RFC header, including links for the
> +    original Debbugs submission.
> + 2. Commit everything.

We should explicitly place the burden here on committers to avoid
ambiguity. e.g. for RFCs that are approved, a committer will merge it in
to the repository.

> +** 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.
> +
> +** Backward Compatibility
> +
> +None.
> +
> +** 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: c0895371c5759c7d9edb330774e90f192cc4cf2c

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