Improving the RFC process: Summary Comments?


#1

Observing the RFCs going through recently, I, and from what I can tell many others, have been overwhelmed by the number of comments and discussions going on. It’s hard for even the RFC author to keep track, let alone community members who wish to contribute.

We’ve already had some proposals in this space. Refining RFCs part 2: RFC staging from http://aturon.github.io/blog/2016/07/05/rfc-refinement/ is one of them. Another idea is the concept of each RFC being its own repo (as the nonlexical lifetimes RFC was), with discussions conducted on issues giving it a more structured view.

These both propose changes to the process. I’m rather positive towards both of them, but changes to the process require far more thought and time.

Instead, I wish to encourage folks to help out within the existing system!

One thing that really helps RFCs is summary comments. Basically, a single comment describing the state of the discussion – linking to each high-level issue, and major opinions on either side of each issue, as well as noting which issues are resolved/unresolved. I recently made a mini-comment of this form in https://github.com/rust-lang/rfcs/pull/2116#issuecomment-327949147 , and I’ve noticed team members making larger versions of this comment on other RFCs in the past.

It would be nice if this was a tiny bit more formalized; with some guidelines on how to make such a comment, and having RFC authors (or others with maintainer access on the rfcs repo) edit the pull request body to link to the recentmost summary.

What do y’all think? Will this help? If so, what exactly should the guidelines be?


#2

I think this is a great idea! I found your comment to be very helpful especially the links to the various major points of discussion. I also really like the comment @aturon left linking to your comment after the final comment period started. I know I’ve opened a FCP issue before and it’s been difficult to determine whether the RFC is being postponed or merged because there has been so much discussion before the FCP starts. I’d love to see a comment after the FCP starts with all of the relevant links consolidated like this (using the fallible allocation RFC as an example):

This RFC is now entering the FCP. The libs team has decided to merge this RFC. @Manishearth has written up a summary comment and the final draft of the RFC is available here.


#3

Assuming we stick with Github as the discussion platform, I really liked this idea – having rfcbot make the second comment in the thread, and then people (anyone? team members? RFC author?) can tell the bot to link a new summary comment from there.

And of course obligatory semi-relevant XKCD (see title text).


#4

At some point I wanted to advocate for a workflow like this:

  • Anybody can say @rfcbot request-summary, this tags thread with needs-summary
  • Anybody else can @rfcbot summarize and then write a summary. This clears the label and adds a link somewhere useful to the summary.

#5

I thought it might be a fun and new way to participate in the Rust project – i.e., rather than contributing code, contributing by helping to summarize and drive RFC discussions. I also definitely agree with @Manishearth that some guidelines would be great. Perhaps even a bit of formatting suggestions and the like.