-
Notifications
You must be signed in to change notification settings - Fork 5
RFC 0001: Bootstrap the RFC Process #1
base: master
Are you sure you want to change the base?
Changes from 1 commit
8da84d2
9410285
deb8172
c15f5ce
ccd1ced
db4e004
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
- 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would add a field here for There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The headers section is getting ugly and overloaded. Instead I tweaked the "Rationale" section to also call for links to prior discussions. |
||
|
||
# Summary | ||
[summary]: #summary | ||
|
||
One paragraph explanation of the feature. | ||
|
||
# Motivation | ||
[motivation]: #motivation | ||
|
||
Why are we doing this? What use cases does it support? What is the expected outcome? | ||
|
||
# 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would replace "language" with "protocol" or "ecosystem" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ replaced with "protocol" |
||
|
||
- Introducing new named concepts. | ||
- Explaining the feature largely in terms of examples. | ||
- Explaining how programmers and other contributors should *think* about the feature, and how it should impact the way they use the software or protocols being modified. It should explain the impact as concretely as possible. | ||
- 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is very specific to Rust. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. good catch. I switched all the other references to "compiler" to instead talk about protocol design. Fixed this one to match. |
||
|
||
# Reference-level explanation | ||
[reference-level-explanation]: #reference-level-explanation | ||
|
||
This is the technical portion of the RFC. Explain the design in sufficient detail that: | ||
|
||
- Its interaction with other features is clear. | ||
- It is reasonably clear how the feature would be implemented. | ||
- Corner cases are dissected by example. | ||
|
||
The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. | ||
|
||
# Drawbacks | ||
[drawbacks]: #drawbacks | ||
|
||
Why should we *not* do this? | ||
|
||
# Rationale and alternatives | ||
[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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||
- What is the impact of not doing this? | ||
|
||
# Unresolved questions | ||
[unresolved]: #unresolved-questions | ||
|
||
- What parts of the design do you expect to resolve through the RFC process before this gets merged? | ||
- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? | ||
- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,240 @@ | ||
IPFS RFCs | ||
===== | ||
|
||
This repository will be the place where people propose, comment on, and refer to RFCs for changes to IPFS and its surrounding projects. Its initial manifestation will probably look a lot like the [Rust lang RFCs repository](https://github.com/rust-lang/rfcs) | ||
## Table of Contents | ||
[Table of Contents]: #table-of-contents | ||
|
||
- [Opening](#rust-rfcs) | ||
- [Table of Contents] | ||
- [When you need to follow this process] | ||
- [Before creating an RFC] | ||
- [What the process is] | ||
- [The RFC life-cycle] | ||
- [Reviewing RFCs] | ||
- [Implementing an RFC] | ||
- [RFC Postponement] | ||
- [Help this is all too informal!] | ||
- [License] | ||
|
||
|
||
## When you need to follow this process | ||
[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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. until there's a libp2p org, with people to run it, these RFCs apply to both. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 👍 sounds good; just wanted to make sure. |
||
"substantial" change is evolving based on community norms and varies depending | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If "substancial" is not clear, we should give a pointer to who can be asked and is going to make a decision. |
||
on what part of the ecosystem you are proposing to change, but may include the | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. are you suggesting a change here? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||
- Adding anything to our list of officially supported projects, libraries, and specifications. | ||
|
||
Some changes do not require an RFC: | ||
|
||
- Rephrasing, reorganizing, refactoring, or otherwise "changing shape does not change meaning". | ||
- Additions that strictly improve objective, numerical quality criteria | ||
(warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.) | ||
- Additions only likely to be _noticed by_ other developers-of-ipfs, but | ||
invisible to users-of-ipfs. | ||
|
||
If you submit a pull request to implement a new feature without going through | ||
the RFC process, it may be closed with a polite request to submit an RFC first. | ||
|
||
|
||
### working group specific guidelines | ||
[working group specific guidelines]: #working group-specific-guidelines | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is rendering in plain text — I think because there’s a space instead of a dash in |
||
|
||
As working groups take form, they will have the perogative to add further guidelines regarding RFCs that apply to their domain of work. | ||
|
||
## Before creating an RFC | ||
[Before creating an RFC]: #before-creating-an-rfc | ||
|
||
A hastily-proposed RFC can hurt its chances of acceptance. Low quality | ||
proposals, proposals for previously-rejected features, or those that don't fit | ||
into the near-term roadmap, may be quickly rejected, which can be demotivating | ||
for the unprepared contributor. Laying some groundwork ahead of the RFC can | ||
make the process smoother. | ||
|
||
Although there is no single way to prepare for submitting an RFC, it is | ||
generally a good idea to pursue feedback from other project developers | ||
beforehand, to ascertain that the RFC may be desirable; having a consistent | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. might be a good idea to mention #ipfs and #ipfs-dev There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ added. |
||
[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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe we should have a specific category in the forum and link directly to it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ created the category and updated the link. |
||
|
||
As a rule of thumb, receiving encouraging feedback from long-standing project | ||
developers, and particularly members of the relevant [working group] is a good | ||
indication that the RFC is worth pursuing. | ||
|
||
|
||
## 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. s/rust/ipfs/g There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ |
||
merged into the RFC repository as a markdown file. At that point the RFC is | ||
"active" and may be implemented with the goal of eventual inclusion into the corresponding protocols or libraries. | ||
|
||
- Fork the RFC repo [RFC repository] | ||
- Copy `0000-template-rfc.md` to `rfcs/0000-my-feature.md` (where "my-feature" is | ||
descriptive. don't assign an RFC number yet). | ||
- Fill in the RFC. Put care into the details: RFCs that do not present | ||
convincing motivation, demonstrate understanding of the impact of the | ||
design, or are disingenuous about the drawbacks or alternatives tend to be | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "the author should be prepared to respond to feedback and possibly revise the proposal" sounds like slightly better wording to me. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ applied. |
||
- Each pull request will be labeled with the most relevant [working group], which | ||
will lead to its being triaged by that team in a future meeting and assigned | ||
to a member of the working group. | ||
- Build consensus and integrate feedback. RFCs that have broad support are | ||
much more likely to make progress than those that don't receive any | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would change
To
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ done. |
||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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.
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. |
||
Specifically, do not squash or rebase commits after they are visible on the | ||
pull request. | ||
- At some point, a member of the working group will propose a "motion for final | ||
comment period" (FCP), along with a *disposition* for the RFC (merge, close, | ||
or postpone). | ||
- This step is taken when enough of the tradeoffs have been discussed that | ||
the working group is in a position to make a decision. That does not require | ||
consensus amongst all participants in the RFC thread (which is usually | ||
impossible). However, the argument supporting the disposition on the RFC | ||
needs to have already been clearly articulated, and there should not be a | ||
strong consensus *against* that position outside of the working group. Working group | ||
members use their best judgment in taking this step, and the FCP itself | ||
ensures there is ample time and notification for stakeholders to push back | ||
if it is made prematurely. | ||
- For RFCs with lengthy discussion, the motion to FCP is usually preceded by | ||
a *summary comment* trying to lay out the current state of the discussion | ||
and major tradeoffs/points of disagreement. | ||
- Before actually entering FCP, *all* members of the working group must sign off; | ||
this is often the point at which many working group members first review the RFC | ||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Change example to IPFS-related? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ |
||
stakeholders have a chance to lodge any final objections before a decision | ||
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. | ||
|
||
## The RFC life-cycle | ||
[The RFC life-cycle]: #the-rfc-life-cycle | ||
|
||
Once an RFC becomes "active" then authors may implement it and submit the | ||
feature as a pull request to the corresponding repo. Being "active" 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. | ||
|
||
Furthermore, the fact that a given RFC has been accepted and is "active" | ||
implies nothing about what priority is assigned to its implementation, nor does | ||
it imply anything about whether an IPFS developer has been assigned the task of | ||
implementing the feature. While it is not *necessary* that the author of the | ||
RFC also write the implementation, it is by far the most effective way to see | ||
an RFC through to completion: authors should not expect that other project | ||
developers will take on responsibility for implementing their accepted feature. | ||
|
||
Modifications to "active" RFCs can be done in follow-up pull requests. We | ||
strive to write each RFC in a manner that it will reflect the final design of | ||
the feature; but the nature of the process means that we cannot expect every | ||
merged RFC to actually reflect what the end result will be at the time of the | ||
next major release. | ||
|
||
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; check | ||
[working group specific guidelines] for more details. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ |
||
|
||
|
||
## Reviewing RFCs | ||
[Reviewing RFCs]: #reviewing-rfcs | ||
|
||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Maybe should be changed to:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just an idea: to remove ambiguity and make interpretation easier for non-native speakers we may consider prefacing the document with this disclaimer:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. got it. I added a paragraph in that section. switched up the language a bit. |
||
|
||
A working group makes final decisions about RFCs after the benefits and drawbacks | ||
are well understood. These decisions can be made at any time, but the working group | ||
will regularly issue decisions. When a decision is made, the RFC pull request | ||
will either be merged or closed. In either case, if the reasoning is not clear | ||
from the discussion in thread, the working group will add a comment describing the | ||
rationale for the decision. | ||
|
||
|
||
## Implementing an RFC | ||
[Implementing an RFC]: #implementing-an-rfc | ||
|
||
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 Rust repository; thus that | ||
associated issue can be assigned a priority via the triage process that the | ||
teams use for all issues in the IPFS repositories. | ||
|
||
The author of an RFC is not obligated to implement it. Of course, the RFC | ||
author (like any other developer) is welcome to post an implementation for | ||
review after the RFC has been accepted. | ||
|
||
If you are interested in working on the implementation for an "active" RFC, but | ||
cannot determine if someone else is already working on it, feel free to ask | ||
(e.g. by leaving a comment on the associated issue). | ||
|
||
|
||
## RFC Postponement | ||
[RFC Postponement]: #rfc-postponement | ||
|
||
Some RFC pull requests are tagged with the "postponed" label when they are | ||
closed (as part of the rejection process). An RFC closed with "postponed" is | ||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This doesn't fit IPFS. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. removed. |
||
requests may be re-opened when the time is right. We don't have any formal | ||
process for that, you should ask members of the relevant working group. | ||
|
||
Usually an RFC pull request marked as "postponed" has already passed an | ||
informal first round of evaluation, namely the round of "do we think we would | ||
ever possibly consider making this change, as outlined in the RFC pull request, | ||
or some semi-obvious variation of it." (When the answer to the latter question | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Does anyone disagree with removing this? It came from the original Rust RFC process There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I feel the message of the section is an important reminder, the title could probably be reworded. |
||
[Help this is all too informal!]: #help-this-is-all-too-informal | ||
|
||
The process is intended to be as lightweight as reasonable for the present | ||
circumstances. As usual, we are trying to let the process be driven by | ||
consensus and community norms, not impose more structure than necessary. | ||
|
||
|
||
[ipfs discussion forum]: https://discuss.ipfs.io/ | ||
[RFC issue tracker]: https://github.com/ipfs/rfcs/issues | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This repo is called There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agree. The repository has bunch of RFCs in it. The repository is not a RFC. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ renamed the repo |
||
[RFC repository]: http://github.com/ipfs/rfcs | ||
[working group]: https://github.com/ipfs/ipfs/pull/285 | ||
|
||
## License | ||
[License]: #license | ||
|
||
This repository is currently in the process of being licensed under MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) | ||
|
||
_The original version of this document was cloned from the [Rust lang RFCs repository](https://github.com/rust-lang/rfcs/blob/752a02115e49c114e2d6b5247c410da69aac505c/README.md), which is dual-licensed under MIT and Apache2 licenses._ | ||
|
||
### Contributions | ||
|
||
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the MIT license, shall be licensed as above, without any additional terms or conditions. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
- Feature Name: bootstrapping-rfc-process | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This RFC is missing There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @flyingzumwalt seems the other RFCs you've done are also missing this, did you use There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @victorbjelkholm they were created before the template was updated. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ added. yes. those fields were added to the template after these PRs were created |
||
- Start Date: 09 February 2018 | ||
- RFC PR: (leave this empty) | ||
- IPFS Issue: (leave this empty) | ||
|
||
# Summary | ||
[summary]: #summary | ||
|
||
Begin using an RFC process. Initially use a structure similar to the process used by the maintainers of Rust lang, as described in https://github.com/rust-lang/rfcs | ||
|
||
# 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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, One example, but it is the same for all of them: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It will come up in the review, and clear up when are few RFCs already out. |
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Typo: “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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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... There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
|
||
# Guide-level explanation | ||
[guide-level-explanation]: #guide-level-explanation | ||
|
||
_[Cribbed directly from [rust-lang/rfcs README](https://github.com/rust-lang/rfcs#rust-rfcs)]_ | ||
Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow. | ||
|
||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Both instances of "language" should be replaced with "protocol" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ replaced with "protocol" |
||
|
||
# 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 [Rust lang RFCs repository](https://github.com/rust-lang/rfcs/blob/752a02115e49c114e2d6b5247c410da69aac505c/README.md), which is dual-licensed under MIT and Apache2 licenses. | ||
|
||
Go to [README.md](../README.md) to review and comment on the details of the proposed process. _[Note: when this RFC is merged, we should update this link to point to the README.md in the specific commit that got merged.]_ | ||
|
||
# Drawbacks | ||
[drawbacks]: #drawbacks | ||
|
||
Why should we *not* do this? | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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):
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✅ added |
||
|
||
# Rationale and alternatives | ||
[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 | ||
- The process described here is sufficiently minimal that we can implement it without much confusion and will be able to modify/improve it over time | ||
- This process is generic enough that we can fork it and repeat on spinoff projects like libp2p, IPLD, etc | ||
|
||
|
||
# Unresolved questions | ||
[unresolved]: #unresolved-questions | ||
|
||
- This process presumes the existence of _working groups_ and describes some of the responsibilities of working groups. Those ideas are subject to change in the next RFC [0002-ipfs-governance.md] which will outline our governance structure. That RFC might change the responsibilities of working groups or replace the notion of working groups with some other structure (ie. sub teams, product groups, functional groups etc.). Because of that, any reference to working groups in this current RFC should be treated as provisional until the governance RFC is merged. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From the Couchbase SDK RFC template I like the additional fields:
The status is described in the Readme.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good idea. I added this, and rearranged the "lifecycle" section to spell out these stages.