RFC 0001: Bootstrap the RFC Process #1
Conversation
README.md
Outdated
| ## What the process is | ||
| [What the process is]: #what-the-process-is | ||
|
|
||
| In short, to get a major feature added to Rust, one must first get the RFC |
README.md
Outdated
| in full depth. | ||
| - The FCP lasts ten calendar days, so that it is open for at least 5 business | ||
| days. It is also advertised widely, | ||
| e.g. in [This Week in Rust](https://this-week-in-rust.org/). This way all |
0000-template-rfc.md
Outdated
| - Feature Name: (fill me in with a unique ident, my_awesome_feature) | ||
| - Start Date: (fill me in with today's date, YYYY-MM-DD) | ||
| - RFC PR: (leave this empty) | ||
| - IPFS Issue: (leave this empty) |
There was a problem hiding this comment.
From the Couchbase SDK RFC template I like the additional fields:
- Owner: [TBD: your name]
- Current Status: TBD: DRAFT -> REVIEW -> ACCEPTED]
The status is described in the Readme.
There was a problem hiding this comment.
Good idea. I added this, and rearranged the "lifecycle" section to spell out these stages.
|
|
||
|
|
||
| [ipfs discussion forum]: https://discuss.ipfs.io/ | ||
| [RFC issue tracker]: https://github.com/ipfs/rfcs/issues |
There was a problem hiding this comment.
This repo is called RFC and not rfcs. Though I'd prefer the lower case plural version.
There was a problem hiding this comment.
Agree. The repository has bunch of RFCs in it. The repository is not a RFC.
There was a problem hiding this comment.
I think someone changed the name of the repo on me. Not sure who did it or how it happened. @lgierth did you change it to RFC?
| 1. Allows everyone to see what decisions have been made and how they were made | ||
| 2. Allows everyone to see what proposals have been proposed and comment on them or ssuggest changes | ||
| 3. Works for a globally distributed group of contributors to discuss and make decisions asynchronously | ||
| 4. Can be replicated/repeated in sibling projects or spinoff projects like libp2p, IPLD, etc. |
There was a problem hiding this comment.
In the beginning, this process applies only for IPFS features or we'll use this repository for proposals for the rest of the projects as well?
There was a problem hiding this comment.
Later RFCs will spell out the org structure, which will decide which projects are affected by the RFCs in this repo. See #2, which proposes making a separate libp2p org. That org might have its own RFCs...
0000-template-rfc.md
Outdated
| [alternatives]: #alternatives | ||
|
|
||
| - Why is this design the best in the space of possible designs? | ||
| - What other designs have been considered and what is the rationale for not choosing them? |
There was a problem hiding this comment.
The guidance questions in this section (particularly the first two) have an air of "make a strong case for why your design is good, and a neutral/weak case for the others". Might be useful to frame it more as "make a strong case for why your design is good, a similarly strong case for why the primary alternatives are good, then explain where the differences are and why yours is better". The idea would be to try to get the writer to steelman (make a strong case for) the alternatives and avoid strawmanning (making a weak case for) them, which could also help them think through/motivate their design even more.
For example, the second question could be split into two questions like "What are the best alternatives to this design, and why are they the best alternatives?" and "What is the rationale for choosing your design over the alternatives? What advantages do the alternatives have over this design?". That way, between the first three questions they argue for their design, the alternatives, and finally the differences (including the ones that make the alternatives better).
There was a problem hiding this comment.
This sounds like something you could put in a blog post. It's overly specific for a document that's meant to define the RFC process in a lightweight way. These should be simple guidelines, not a full-blown rhetoric lesson. Maybe you could use this rhetorical approach in an RFC that you submit and then write a blog post explaining what you did and how it made the RFC better?
There was a problem hiding this comment.
Gotcha, yeah I can see why it'd make sense to not introduce a change like this -- opens the door to a lot of potential 'rhetoric tips' that would dilute the simple guidelines. Also the question in the previous section, 'Why should we not do this?' is a good step in the same direction, not sure whether I considered that last time.
That's a good idea on the blog post, and would be fun to write. I'll keep that in mind.
0000-template-rfc.md
Outdated
| - Feature Name: (fill me in with a unique ident, my_awesome_feature) | ||
| - Start Date: (fill me in with today's date, YYYY-MM-DD) | ||
| - RFC PR: (leave this empty) | ||
| - IPFS Issue: (leave this empty) |
There was a problem hiding this comment.
I would add a field here for Prior discussions that would allow to add bigger context and possible previous commentary that lead to establishment of the RFC as it is seen in here.
There was a problem hiding this comment.
The headers section is getting ugly and overloaded. Instead I tweaked the "Rationale" section to also call for links to prior discussions.
0000-template-rfc.md
Outdated
| - If applicable, provide sample error messages, deprecation warnings, or migration guidance. | ||
| - If applicable, describe the differences between teaching this to existing contributors and new contributors. | ||
|
|
||
| For implementation-oriented RFCs (e.g. for compiler internals), this section should focus on how compiler contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms. |
There was a problem hiding this comment.
good catch. I switched all the other references to "compiler" to instead talk about protocol design. Fixed this one to match.
README.md
Outdated
| minor changes should be submitted as amendments. More substantial changes | ||
| should be new RFCs, with a note added to the original RFC. Exactly what counts | ||
| as a "very minor change" is up to the working group to decide; check | ||
| [working group specific guidelines] for more details. |
There was a problem hiding this comment.
I would suggest adding a point in a header of the RFC if it was changed, including date and very short summary of the change. This way the change is very explicit and hard to miss.
README.md
Outdated
| marked as such because we want neither to think about evaluating the proposal | ||
| nor about implementing the described feature until some time in the future, and | ||
| we believe that we can afford to wait until then to do so. Historically, | ||
| "postponed" was used to postpone features until after 1.0. Postponed pull |
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| Establish a clear, repeatable process for people to propose ideas and make decisions in a way that |
There was a problem hiding this comment.
I think it would be best if supporting questions were removed from RFC in its final form. They just decrease Signal to Noise ratio.
There was a problem hiding this comment.
I don't understand what you're proposing here. What supporting questions? Where in the document are you suggesting they should be removed from? At what point in the process should they be removed? Who should remove them? Why should they remove them?
There was a problem hiding this comment.
I'm saying, the questions from the RFC template should not be part of final RFC documents.
See all of rusts RFC documents. For example, motivation section does not contain the "Establish a clear, repeatable process for people to propose ideas and make decisions in a way that" from template.
One example, but it is the same for all of them:
https://github.com/rust-lang/rfcs/blob/master/text/2333-prior-art.md
There was a problem hiding this comment.
Do you have a suggestion of how to encourage people to do this? It seems to work fine with Rust using the template and RFC process as-is. Do you want to add a step to the process where someone has to check if these are removed?
There was a problem hiding this comment.
It will come up in the review, and clear up when are few RFCs already out.
From the beginning I treated it like that (I started writing few RFCs already), remove the questions after that part is written. I think we don't need to add anything to the process for it apart from making sure that all RFCs are clear of it.
|
Applied all of the suggested changes, except one suggestion that I didn't understand (see comments) |
| @@ -43,7 +43,7 @@ Why should we *not* do this? | |||
| [alternatives]: #alternatives | |||
|
|
|||
| - It's time to establish a clear, reliable process for proposing changes and tracking the decisions we've made. If done right, this will do a lot to reduce confusion, encourage participation, and encourage a high level of transparency around important decisions that impact the project. | |||
| - Rather than starting from scratch, we're starting with the process that is being used, successfully, by a project we admire -- the Rust language | |||
| - Rather than starting from scratch, we're starting with the process that is being used, successfully, by a project we admire -- the IPFS language | |||
There was a problem hiding this comment.
reference to Rust was removed from here, I think the regex was a bit overzealous.
README.md
Outdated
|
|
||
|
|
||
| ### working group specific guidelines | ||
| [working group specific guidelines]: #working group-specific-guidelines |
There was a problem hiding this comment.
This is rendering in plain text — I think because there’s a space instead of a dash in #working group.
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| Begin using an RFC process. Initially use a structure similar to the process used by the maintainers of IPFS lang, as described in https://github.com/IPFS-lang/rfcs |
There was a problem hiding this comment.
This should be https://github.com/ipfs/rfcs, right? (not IPFS-lang/rfcs)
There was a problem hiding this comment.
Or is this actually supposed to be a reference to Rust, since you’re saying that’s what this is similar to? In either case, the link is wrong :P
| # Reference-level explanation | ||
| [reference-level-explanation]: #reference-level-explanation | ||
|
|
||
| The proposed RFC process is described in the [README](../README.md). It's a modified version of the process used in the [IPFS lang RFCs repository](https://github.com/IPFS-lang/rfcs/blob/752a02115e49c114e2d6b5247c410da69aac505c/README.md), which is dual-licensed under MIT and Apache2 licenses. |
There was a problem hiding this comment.
Same note as up on line 9 — is this supposed to be the “IPFS RFCs repository” and link to ipfs/rfcs/xyz/README.md or to “Rust Lang RFCs repository” and link to rust-lang/rfcs/xyz/README.md? It’s halfway between those now, so doesn’t seem correct no matter what.
| # Guide-level explanation | ||
| [guide-level-explanation]: #guide-level-explanation | ||
|
|
||
| _[Cribbed directly from [IPFS-lang/rfcs README](https://github.com/IPFS-lang/rfcs#IPFS-rfcs)]_ |
There was a problem hiding this comment.
Same note as up on line 9 — is this supposed to be ipfs/rfcs#IPFS-rfcs or rust-lang/rfcs#Rust-rfcs?
|
|
||
| Establish a clear, repeatable process for people to propose ideas and make decisions in a way that | ||
| 1. Allows everyone to see what decisions have been made and how they were made | ||
| 2. Allows everyone to see what proposals have been proposed and comment on them or ssuggest changes |
| [When you need to follow this process]: #when-you-need-to-follow-this-process | ||
|
|
||
| You need to follow this process if you intend to make "substantial" changes to | ||
| IPFS, libp2p or the RFC process itself. What constitutes a |
There was a problem hiding this comment.
Is “libp2p” correct here? RFC 0001 talks about replicating this process over in the libp2p org, so I would assume the process here is not the right one for libp2p. Or are we going to do it all here for now until we decide it makes sense to replicate all this in the other orgs?
There was a problem hiding this comment.
until there's a libp2p org, with people to run it, these RFCs apply to both.
There was a problem hiding this comment.
👍 sounds good; just wanted to make sure.
|
Thanks for catching those typos @Mr0grog. I fixed them. |
| following. | ||
|
|
||
| - Any semantic or syntactic change to the protocols that is not a bugfix. | ||
| - Removing protocol features, including those that are feature-gated. |
There was a problem hiding this comment.
"feature-gated" in this context means "feature flags" I'm guessing? So even removing experimental features, would need an RFC?
There was a problem hiding this comment.
are you suggesting a change here?
There was a problem hiding this comment.
I'm unsure if I want to suggest a change as I'm unsure if "feature-gated" refers to "feature flags" and experimental features. If it does, I'm unsure if we want to go through a RFC process to change/remove them, as they are marked as experimental just because we want the process to be lighter around changing them.
If it's referring to something else, I'd like it to be clarified as I don't know what it means.
README.md
Outdated
| impact on the project requires concerted effort toward consensus-building. | ||
|
|
||
| The most common preparations for writing and submitting an RFC include talking | ||
| the idea over on the #ipfs irc channel, filing and discussing ideas on the |
There was a problem hiding this comment.
might be a good idea to mention #ipfs and #ipfs-dev
README.md
Outdated
|
|
||
| ### Status: Accepted | ||
|
|
||
| Once an RFC becomes "Accepted" then authors may implement it and submit the |
There was a problem hiding this comment.
submit the feature as a pull request
This refers to creating a new PR made to a specific repository? Or the one created in this repository for the draft? In that case, it just has to be merged as it was created in the draft stage already.
There was a problem hiding this comment.
"submit the feature as a pull request to the corresponding repo" seems pretty clear to me. I take it to mean that once the RFC is Accepted you can make corresponding changes to the necessary repositories and code bases by submitting PRs. Can you suggest a change that makes it clearer?
| In general, once accepted, RFCs should not be substantially changed. Only very | ||
| minor changes should be submitted as amendments. More substantial changes | ||
| should be new RFCs, with a note added to the original RFC. Exactly what counts | ||
| as a "very minor change" is up to the working group to decide. |
There was a problem hiding this comment.
I think it's safe to say that everything but cosmetic changes (spell fixes and so on, "changing shape does not change meaning") should be a new RFC, and not up to the working groups to modify RFCs as they see fit
There was a problem hiding this comment.
Are you suggesting a modification to the text here? I think the current wording allows for the usage that you're describing. We should avoid making this initial document too specific or rigid.
README.md
Outdated
| While the RFC pull request is up, the working group may schedule meetings with the | ||
| author and/or relevant stakeholders to discuss the issues in greater detail, | ||
| and in some cases the topic may be discussed at a working group meeting. In either | ||
| case a summary from the meeting will be posted back to the RFC pull request. |
There was a problem hiding this comment.
from the meeting will be posted back to the RFC pull request
Maybe should be changed to:
from the meeting must be posted back to the RFC pull request
There was a problem hiding this comment.
Just an idea: to remove ambiguity and make interpretation easier for non-native speakers we may consider prefacing the document with this disclaimer:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119
There was a problem hiding this comment.
switching to "must". @lidel I like your suggestion but not sure where in the document to put it. Do you have an idea of which section or which line I should add it to?
There was a problem hiding this comment.
@flyingzumwalt I'd expect it to be in "Before creating an RFC" section, as part of setting some ground rules/mindset for writing a new RFC.
It could be just a paragraph at the end. My english is clunky, but maybe something ~ to this: "In an effort to avoid ambiguity assume that the key words [...] in your RFC will be interpreted as described in IETF's RFC 2119 "
That way a person writing new RFC will automatically start paying attention to these keywords.
There was a problem hiding this comment.
got it. I added a paragraph in that section. switched up the language a bit.
README.md
Outdated
| Some accepted RFCs represent vital features that need to be implemented right | ||
| away. Other accepted RFCs can represent features that can wait until some | ||
| arbitrary developer feels like doing the work. Every accepted RFC has an | ||
| associated issue tracking its implementation in the IPFS repository; thus that |
There was a problem hiding this comment.
What's "the IPFS repository"? github.com/ipfs/ipfs?
There was a problem hiding this comment.
✅ changed to "the corresponding IPFS repository"
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
| Why should we *not* do this? |
There was a problem hiding this comment.
This does not feel very fleshed out yet. Few reasons I can come up with (that I don't necessary agree with, but to start something):
- Introducing too much of process, leading to developers not approaching the project in fear of too process-heavy
- It can be hard to reach consensus on some broad changes, without having one person being the decision maker
- Decisions can be made implicitly without going through the RFC process, and this repository still won't be the source of truth for design decisions
- Yet another repository on the IPFS Github to manage and participate in
- Not being a formal enough process to be valuable
README.md
Outdated
| The most common preparations for writing and submitting an RFC include talking | ||
| the idea over on the #ipfs irc channel, filing and discussing ideas on the | ||
| [RFC issue tracker], and occasionally posting "pre-RFCs" on the | ||
| [ipfs discussion forum](https://discuss.ipfs.io) for early review. |
There was a problem hiding this comment.
Maybe we should have a specific category in the forum and link directly to it?
There was a problem hiding this comment.
✅ created the category and updated the link.
README.md
Outdated
| poorly-received. | ||
| - Submit a pull request. As a pull request the RFC will receive design | ||
| feedback from the larger community, and the author should be prepared to | ||
| revise it in response. |
There was a problem hiding this comment.
"the author should be prepared to respond to feedback and possibly revise the proposal" sounds like slightly better wording to me.
README.md
Outdated
| comments. Feel free to reach out to the RFC assignee in particular to get | ||
| help identifying stakeholders and obstacles. | ||
| - The working group will discuss the RFC pull request, as much as possible in the | ||
| comment thread of the pull request itself. Offline discussion will be |
There was a problem hiding this comment.
I would change
Offline discussion will be summarized on the pull request comment thread
To
Offline discussion must be summarized on the pull request comment thread
| - RFCs rarely go through this process unchanged, especially as alternatives | ||
| and drawbacks are shown. You can make edits, big and small, to the RFC to | ||
| clarify or change the design, but make changes as new commits to the pull | ||
| request, and leave a comment on the pull request explaining your changes. |
There was a problem hiding this comment.
and leave a comment on the pull request explaining your changes
That feels unnecessary, the git commit should have a proper title + description, and no comment explaining the changes are needed. Maybe just a commit to ping relevant people when updated would be better.
There was a problem hiding this comment.
I disagree. Sometimes the comment on the PR will be a repetition of the description in the commit, which is still useful, but often people will provide fuller explanations when prompted -- explanations that are too lengthy for a git commit, or are full of links which will be more readable in a markdown-based comment on the PR.
There was a problem hiding this comment.
Problem with leaving PR commands to explain the changes instead of in the Git history, is that we're disconnecting the changes from the explanations of the changes. When you pull down the repository locally, you'll be able to see the explanations if it's in the commits, if it's only in the PR, the information becomes harder to find and also not as accessible.
explanations that are too lengthy for a git commit
I don't see this as possible, you have the body of the commit where you can elaborate how much you want on the reasoning of the change. This should be happening anywhere, and the comment on the PR would simply be a duplication of this. But if we want to copy-paste it into the PR, fine.
README.md
Outdated
| is reached. | ||
| - In most cases, the FCP period is quiet, and the RFC is either merged or | ||
| closed. However, sometimes substantial new arguments or ideas are raised, | ||
| the FCP is canceled, and the RFC goes back into development mode. |
There was a problem hiding this comment.
"and the RFC goes back into development mode" should be clearer. If I understand correctly, it goes back into the "Review" stage.
| @@ -0,0 +1,54 @@ | |||
| - Feature Name: bootstrapping-rfc-process | |||
There was a problem hiding this comment.
This RFC is missing Current Status and Owner headers
There was a problem hiding this comment.
@flyingzumwalt seems the other RFCs you've done are also missing this, did you use 0000-template-rfc.md as a template for these?
There was a problem hiding this comment.
@victorbjelkholm they were created before the template was updated.
There was a problem hiding this comment.
✅ added. yes. those fields were added to the template after these PRs were created
README.md
Outdated
| merged into the RFC repository as a markdown file. At that point the RFC is | ||
| "Accepted" and may be implemented with the goal of eventual inclusion into the corresponding protocols or libraries. | ||
|
|
||
| As it grows from an idea to shipping in a supported release, an SDK RFC will traverse along: |
There was a problem hiding this comment.
This section mentions "SDK" a lot as it was copied from the Couchbase one. It should probably just sat "RFC"
I also asked for permission to copy & paste this section, it was granted. Could give credit/thanks/whatever in the readme to the Couchbase SDK one, I think that would be fair.
There was a problem hiding this comment.
could I get a link for citing the Couchbase source?
There was a problem hiding this comment.
README.md
Outdated
|
|
||
| 1. **Draft**: The owner of the SDK RFC has started to draft up how the subject will be handled and may be reviewing with a core group. Comments are certainly welcome at this stage even though the owner hasn't worked through enough details to ask for... | ||
| 2. **Review**: This SDK RFC is in a review period. Stakeholders and the owner may still be iterating on some final details before signoff. A minimum review period has been defined. | ||
| 3. **Final Call** |
There was a problem hiding this comment.
It would be cool to have a short description here as well.
There was a problem hiding this comment.
✅ added short description
|
|
||
| You need to follow this process if you intend to make "substantial" changes to | ||
| IPFS, libp2p or the RFC process itself. What constitutes a | ||
| "substantial" change is evolving based on community norms and varies depending |
There was a problem hiding this comment.
If "substancial" is not clear, we should give a pointer to who can be asked and is going to make a decision.
| is "no", then the appropriate response is to close the RFC, not postpone it.) | ||
|
|
||
|
|
||
| ### Help this is all too informal! |
There was a problem hiding this comment.
I would remove this section.
Personally, I feel it's very formal, but I see the need to have it around as a tool that can be used as needed.
There was a problem hiding this comment.
Does anyone disagree with removing this? It came from the original Rust RFC process
There was a problem hiding this comment.
I feel the message of the section is an important reminder, the title could probably be reworded.
0000-template-rfc.md
Outdated
| # Guide-level explanation | ||
| [guide-level-explanation]: #guide-level-explanation | ||
|
|
||
| Explain the proposal as if it was already included in the language and you were teaching it to another contributor on this project. That generally means: |
There was a problem hiding this comment.
I would replace "language" with "protocol" or "ecosystem"
There was a problem hiding this comment.
✅ replaced with "protocol"
|
|
||
| Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the IPFS community and the sub-teams. | ||
|
|
||
| The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the language and standard libraries, so that all stakeholders can be confident about the direction the language is evolving in. |
There was a problem hiding this comment.
Both instances of "language" should be replaced with "protocol"
There was a problem hiding this comment.
✅ replaced with "protocol"
README.md
Outdated
|
|
||
| As it grows from an idea to shipping in a supported release, an SDK RFC will traverse along: | ||
|
|
||
| 1. **Draft**: The owner of the SDK RFC has started to draft up how the subject will be handled and may be reviewing with a core group. Comments are certainly welcome at this stage even though the owner hasn't worked through enough details to ask for... |
There was a problem hiding this comment.
I think it was already noted that "Core" is bit ambiguous in PL, perhaps "core group" → "relevant working group" ?
README.md
Outdated
| As it grows from an idea to shipping in a supported release, an SDK RFC will traverse along: | ||
|
|
||
| 1. **Draft**: The owner of the SDK RFC has started to draft up how the subject will be handled and may be reviewing with a core group. Comments are certainly welcome at this stage even though the owner hasn't worked through enough details to ask for... | ||
| 2. **Review**: This SDK RFC is in a review period. Stakeholders and the owner may still be iterating on some final details before signoff. A minimum review period has been defined. |
There was a problem hiding this comment.
A minimum review period has been defined.
Defined.. where? I'd make this more precise, eg. defined in the PR.
There was a problem hiding this comment.
I'm just taking that sentence out because it's not clear. If someone wants to propose a minimum review period we can add it back in.
| in full depth. | ||
| - The FCP lasts ten calendar days, so that it is open for at least 5 business | ||
| days. It is also advertised widely, | ||
| e.g. in the [Weekly IPFS All Hands Call](https://github.com/ipfs/pm/#weekly-all-hands). This way all |
There was a problem hiding this comment.
Maybe a personal preference of mine, but I think any broadcasts, such as status changes of RFCs, should be announced on an RFC specific mailing list so that they don't get lost in meeting notes.
Uses Rust-inspired RFC process to propose using Rust-inspired RFC process as a starting point.