Thoughts on an RFD (request for discussion) process

[dontlaugh]

The Problem

The issues on this repo are quite active, but actual git commits aren't.

That's a problem. The longer discussion on an issue continues, consensus and resolution become harder to achieve. I believe that's because issues direct energy into unproductive areas. I believe this is this case even if the discussion is high quality. The discussions on issues in this repo are often high quality, but the UX of issues is a black hole that sucks energy.

Discussion on a PR is better than issues. A PR gives the reviewer an opportunity to discuss and resolve specific bits of language. Everyone on a PR is working towards a common goal: to make the PR more correct, less ambiguous, etc. Issues can achieve this, but the mental energy required is way higher.

Doing Things Differently

I'd like everyone to read the Oxide RFD process, and see what they think of it.

Some key differences with what we have now:

• Merging an RFD doesn't automatically sign you up for a new side job of implementing it end-to-end; it simply means an RFD has been reviewed, and the document that ultimately gets merged has value.
• Adopt a flat structure and a numbering scheme that's disconnected from issue numbers
• Redirect most of the energy going back and forth on issues towards collaborative editing and discussion on PRs
• RFDs can and should be edited after the fact; discussion can be revived; things can change

In practical terms, I think what this means for us is

• PRs get opened way way sooner
• We de-emphasize the notion of "solutions" in this repo, and instead focus on high quality writing, such as
  • Lucid, nuanced descriptions of complex problems
  • Good high level requirements
  • Good descriptions of architecture, whether existing or proposed
  • Language changes
• We de-emphasize the "who is gonna implement it" stuff

Concrete Example

Recently, Liz opened an issue that I think would be the basis of a good RFD. Here it is

#443

So imagine something like that, but as a file that lives here

problem-solving/
  rfd/
    0091-make-z-and-friends-dwim.md

---

The gambit here is that the RFD documents themselves deliver value by their very nature, because they've been collaboratively edited and discussed by community members. We already have lots of discussion (I see it on IRC and issues all day). This is a way we can leverage that energy even more.

[dontlaugh]

PS thanks to @coke for opening a PR to this repo. It got me thinking.

If people find this agreeable, I can kick things off with our own Raku version of RFD 1, the "RFD about the RFD process" :)

[niner]

I think this has merit and is worth a try!

[melezhik]

I took a brief reading on RFD doc, so the main idea as I see it is to instead of discussing / describe things in gh issue, propose an idea via git branch, make PR but still discuss in gh PR? In terms of discussion mechanism if you will, I imho, don’t see significant difference.

[melezhik]

Nobody prevents now to define changes or high level design document in any format and link it to gh issue in this repo, does not it?

[dontlaugh]

I think there's a difference, because at the end of a PR disussion, we have a collaboratively edited - or at least collabartively discussed - document. If we give this document a number, then anyone can unambiguously refer to it weeks, months, years from now.

Strictly speaking, @melezhik is correct that nothing prohibits community members from taking this approach today. However, as it stands, we aren't producing a lot of organized engineering documents here, even though we have a lot of high quality discussion. I think we can make changes to the policies outlined in this repo's readme to change that.

[melezhik]

@dontlaugh thanks for reply, does RFD define a structure of RFD document itself? Like some people might use text descriptions plus diagrams made in draw.io in gets embedded as pictures right into markdown, other people something else, also what is a level of granularity / details when we speak about such abstract things like design / architecture changes proposal.

I believe this should not be specified in RDF standard, however what else this RDF will add to our productivity besides RDF doc numbers and statuses? Just thinking out loud )

[dontlaugh]

I believe this should not be specified in RDF standard

I think I agree with you that RFD should be very open as to what's considered acceptable.

Lets go through a series of imaginary examples. I'd consider all three of these to be appropriate documents for discussion.

rfd/
  0009-conference-location.md    # "In person Raku conferences should always
                                 #  be held near beautiful beaches"
  0102-moarvm-dep-vendoring.md   # "Requirements for dependency vendoring in MoarVM"
  0103-rfd-documents-metadata.md # "Metadata that should be parsable from RFDs"

We can imagine each of these PRs being opened and discussed, then finally merged. They are merged because we want a record of the proposal.

RFD 0009 is discussed and it's pretty clear that - during the discussion - the majority of people involved think it's a bad idea. It excludes beautiful mountains, and there's no reason to limit venues in that way. The authors of the RFD, while not convinced, defer to the opinion of the majority.

 = RFD 0009 Raku Conferences Are Beach-Only

-:state: discussion
+:state: abandoned

RFD 0102 is more technical, and the discussion had less controversy. There are many unanswered questions, but those involved have agreed that the requirments laid out in RFD 0102 are a direction we want to move in. The RFD is published.

= RFD 0102 Requirements for MoarVM Dependency Vendoring

-:state: discussion
+:state: published

Over the next year, issues on the MoarVM GitHub repo make reference to this RFD. A few small PRs are made to the RFD as well. When someone wants to package MoarVM for the Chimera Linux distro, they can appeal to the RFD to see how dependencies ought to be managed, even if there's stil work to do on either side.

RFD 0103 is created when someone wants to do analysis on RFDs, and notices that the RFDs could be better organized. They propose some sort of header format and write a script to 1) update existing RFDs, and 2) help to generate new ones. The script is checked into this repo along with the RFD.

= RFD 0103 Metadata that should be parsable from RFDs

-:state: discussion
+:state: published

Over the next year, one or two bugs are fixed in the script. These are PRs, but not amendments to the RFD. One amendment is created, to add a new field which we agree should be parsable.

---

That was just me using my imagination, combined with my experience of lurking in several open source communities (forums and chatrooms) for many years.

Here's some additional prior art we can review:

The Rust RFC process - This site has a lot of language-level discussion, as well as philosophical discussion of the process itself.

---

@melezhik Besides numbers and organized documents, I think a greater focus on editing and refining RFDs can help the Raku Steering Council do its work. In the recent Rakudo Weekly newsletter, we see a link to the issues in this repository tagged RSC Review

RSC Review This issue will be reviewed by the RSC and decided upon soon

Consider in particular issue 4. Lots of good discussion. But wouldn't it be nice if along the way those contributors were collaboratively producing a document that synthesized the proposed APIs and requirements? For those involved in the discussion, it is only a little bit more work, but the outcome (some succinct document that is a starting point for reviving discussion) is much better for all. Now consider that good outcome over and over again, for years.

That's my belief, anyway.