Skip to content
This repository has been archived by the owner on Apr 29, 2020. It is now read-only.

RFC 0001: Bootstrap the RFC Process #1

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions 0000-template-rfc.md
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)
Copy link

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:

  • Owner: [TBD: your name]
  • Current Status: TBD: DRAFT -> REVIEW -> ACCEPTED]

The status is described in the Readme.

Copy link
Author

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The 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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would replace "language" with "protocol" or "ecosystem"

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is very specific to Rust.

Copy link
Author

Choose a reason for hiding this comment

The 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?
Copy link

@dgrisham dgrisham Feb 22, 2018

Choose a reason for hiding this comment

The 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).

Copy link
Author

Choose a reason for hiding this comment

The 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?

Copy link

Choose a reason for hiding this comment

The 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?
238 changes: 237 additions & 1 deletion README.md
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
Copy link

Choose a reason for hiding this comment

The 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?

Copy link
Author

Choose a reason for hiding this comment

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

Copy link

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The 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?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are you suggesting a change here?

Copy link

Choose a reason for hiding this comment

The 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
Copy link

Choose a reason for hiding this comment

The 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 #working group.


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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be a good idea to mention #ipfs and #ipfs-dev

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The 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?

Copy link
Author

Choose a reason for hiding this comment

The 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/rust/ipfs/g

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

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

Copy link

Choose a reason for hiding this comment

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

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.

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change example to IPFS-related?

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

@Kubuxu Kubuxu Feb 23, 2018

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The 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:

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

Copy link
Author

Choose a reason for hiding this comment

The 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?

Copy link

@lidel lidel May 11, 2018

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't fit IPFS.

Copy link
Author

Choose a reason for hiding this comment

The 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!
Copy link
Member

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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

Choose a reason for hiding this comment

The 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This repo is called RFC and not rfcs. Though I'd prefer the lower case plural version.

Copy link

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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?

Copy link
Author

Choose a reason for hiding this comment

The 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.
54 changes: 54 additions & 0 deletions rfcs/0001-bootstrapping-rfc-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
- Feature Name: bootstrapping-rfc-process
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This RFC is missing Current Status and Owner headers

Copy link

Choose a reason for hiding this comment

The 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 0000-template-rfc.md as a template for these?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@victorbjelkholm they were created before the template was updated.

Copy link
Author

Choose a reason for hiding this comment

The 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
Copy link

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The 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?

Copy link

@Kubuxu Kubuxu Mar 3, 2018

Choose a reason for hiding this comment

The 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, 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

Copy link
Author

Choose a reason for hiding this comment

The 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?

Copy link

Choose a reason for hiding this comment

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

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
Copy link

Choose a reason for hiding this comment

The 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.
Copy link

Choose a reason for hiding this comment

The 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?

Copy link
Author

Choose a reason for hiding this comment

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops - #3 is the libp2p RFC. #2 is the (very incomplete) proposal for org structure


# 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both instances of "language" should be replaced with "protocol"

Copy link
Author

Choose a reason for hiding this comment

The 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?
Copy link

Choose a reason for hiding this comment

The 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):

  • 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

Copy link
Author

Choose a reason for hiding this comment

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