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

RFC 0001: Bootstrap the RFC Process #1

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8da84d2
propose Rust-inspired RFC process
Feb 10, 2018
9410285
apply changes suggested in PR comments
Mar 3, 2018
deb8172
fix mis-applied regex
Mar 5, 2018
c15f5ce
fix typos
Mar 19, 2018
ccd1ced
applying changes to 0001 based on comments in the PR
May 11, 2018
db4e004
added reference to IETF RFC 2119 about terms like MUST and SHOULD
May 11, 2018
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
8 changes: 6 additions & 2 deletions 0000-template-rfc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
- Feature Name: (fill me in with a unique ident, my_awesome_feature)
- Start Date: (fill me in with today's date, YYYY-MM-DD)
- Current Status: (DRAFT -> REVIEW -> ACCEPTED) _The status is described in the [Readme](README.md#the-rfc-life-cycle)._
- Owner: (your name and github handle)
- 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

Expand All @@ -24,7 +27,7 @@ Explain the proposal as if it was already included in the language and you were
- 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.
For implementation-oriented RFCs (e.g. for changes to a protocol or its implementations), this section should focus on how protocol 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.

# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation
Expand All @@ -42,12 +45,13 @@ The section should return to the examples given in the previous section, and exp

Why should we *not* do this?

# Rationale and alternatives
# Rationale, Prior Discussion 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 •
edited
Loading

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?
- What prior discussions have occurred that led to this RFC (include links where possible)

# Unresolved questions
[unresolved]: #unresolved-questions
Expand Down
112 changes: 67 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@ IPFS RFCs
## Table of Contents
[Table of Contents]: #table-of-contents

- [Opening](#rust-rfcs)
- [Opening](#ipfs-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]
Expand Down Expand Up @@ -45,7 +44,7 @@ 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.
As working groups take form, they will have the prerogative 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
Expand All @@ -71,12 +70,25 @@ 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
## The RFC life-cycle
[The RFC life-cycle]: #the-rfc-life-cycle

In short, to get a major feature added to Rust, one must first get the RFC
In short, to get a major feature added to IPFS, one must first get the RFC
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.
"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:
Copy link

Choose a reason for hiding this comment

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

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.

Copy link
Author

Choose a reason for hiding this comment

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

could I get a link for citing the Couchbase source?

Copy link

Choose a reason for hiding this comment

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

https://github.com/couchbaselabs/sdk-rfcs :)


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

@lidel lidel May 11, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

I think it was already noted that "Core" is bit ambiguous in PL, perhaps "core group" → "relevant working group" ?

Copy link
Author

Choose a reason for hiding this comment

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

✅ replaced.

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

Choose a reason for hiding this comment

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

A minimum review period has been defined.

Defined.. where? I'd make this more precise, eg. defined in the PR.

Copy link
Author

Choose a reason for hiding this comment

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

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.

3. **Final Call**
Copy link

Choose a reason for hiding this comment

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

It would be cool to have a short description here 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.

✅ added short description

4. **Accepted**: All stakeholders have signed off and this SDK RFC is now or will be implemented soon.


### Status: Draft

When you've done the preparation described in [Before creating an RFC] and are ready to submit your RFC, create the pull request following these steps:


- Fork the RFC repo [RFC repository]
- Copy `0000-template-rfc.md` to `rfcs/0000-my-feature.md` (where "my-feature" is
Expand All @@ -88,9 +100,15 @@ merged into the RFC repository as a markdown file. At that point the RFC is
- 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.


### Status: Review

Once a an RFC has been submitted, it's ready for Review.

- 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.
- At this point, the status in the RFC markdown document should be marked "Review"
- 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
Expand All @@ -104,51 +122,56 @@ merged into the RFC repository as a markdown file. At that point the RFC is
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
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
### Status: Final Call (FCP)

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

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
- 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 the [Weekly IPFS All Hands Call](https://github.com/ipfs/pm/#weekly-all-hands). 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.

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.

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

Choose a reason for hiding this comment

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

"and the RFC goes back into development mode" should be clearer. If I understand correctly, it goes back into the "Review" stage.

Copy link
Author

Choose a reason for hiding this comment

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

✅ done


### Status: Accepted

Once an RFC becomes "Accepted" then authors may implement it and submit the
Copy link

Choose a reason for hiding this comment

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

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.

Copy link
Author

Choose a reason for hiding this comment

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

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

feature as a pull request to the corresponding repo. Being "Accepted" 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"
Furthermore, the fact that a given RFC has been accepted and is "Accepted"
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
### Modifications to Accepted RFCs

Modifications to "Accepted" 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
Expand All @@ -157,9 +180,9 @@ 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.
as a "very minor change" is up to the working group to decide.
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'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

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


_If_ you make changes to an RFC after it's been accepted, add a note in the header of the RFC with a very short summary of the change and links to any relevant discussions. This way the change is very explicit and hard to miss.

## Reviewing RFCs
[Reviewing RFCs]: #reviewing-rfcs
Expand All @@ -183,15 +206,15 @@ rationale for the decision.
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 tracking its implementation in the IPFS repository; thus that
Copy link

@victorb victorb Mar 20, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

What's "the IPFS repository"? github.com/ipfs/ipfs?

Copy link
Author

Choose a reason for hiding this comment

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

✅ changed to "the corresponding IPFS repository"

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
If you are interested in working on the implementation for an "Accepted" 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).

Expand All @@ -203,8 +226,7 @@ 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
we believe that we can afford to wait until then to do so. Postponed pull
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.

Expand Down
8 changes: 4 additions & 4 deletions rfcs/0001-bootstrapping-rfc-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# 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
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
Copy link

Choose a reason for hiding this comment

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

This should be https://github.com/ipfs/rfcs, right? (not IPFS-lang/rfcs)

Copy link

Choose a reason for hiding this comment

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

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


# Motivation
[motivation]: #motivation
Expand All @@ -20,7 +20,7 @@ Establish a clear, repeatable process for people to propose ideas and make decis
# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

_[Cribbed directly from [rust-lang/rfcs README](https://github.com/rust-lang/rfcs#rust-rfcs)]_
_[Cribbed directly from [IPFS-lang/rfcs README](https://github.com/IPFS-lang/rfcs#IPFS-rfcs)]_
Copy link

@Mr0grog Mr0grog Mar 19, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Same note as up on line 9 — is this supposed to be ipfs/rfcs#IPFS-rfcs or 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.
Expand All @@ -30,7 +30,7 @@ The "RFC" (request for comments) process is intended to provide a consistent and
# 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.
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.
Copy link

Choose a reason for hiding this comment

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

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.


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.]_

Expand All @@ -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
Copy link

Choose a reason for hiding this comment

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

reference to Rust was removed from here, I think the regex was a bit overzealous.

Copy link
Author

Choose a reason for hiding this comment

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

thanks. fixed it.

- 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

Expand Down