Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Give pre-RFC suggestions and clarify PR process #506

Merged
merged 3 commits into from
Dec 11, 2014
Merged

Give pre-RFC suggestions and clarify PR process #506

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
421f2c1
Give pre-RFC suggestions and clarify PR process
brson Dec 5, 2014
0736e93
Typo
brson Dec 8, 2014
9390093
Add some text about who is responsible for implementing RFCs
brson Dec 8, 2014
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
122 changes: 81 additions & 41 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,12 @@ the direction the language is evolving in.
* [Active RFC List]
* [Table of Contents]
* [When you need to follow this process]
* [Before creating an RFC]
* [What the process is]
* [The role of the shepherd]
* [The RFC life-cycle]
* [Implementing an RFC]
* [Reviewing RFC's]
* [Implementing an RFC]
* [RFC Postponement]
* [Help this is all too informal!]

Expand Down Expand Up @@ -99,8 +100,38 @@ 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.

## 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 #rust-internals, filing and discusssing ideas
on the [RFC issue tracker][issues], and occasionally posting
'pre-RFCs' on [the developer discussion forum][discuss] for early
review.

As a rule of thumb, receiving encouraging feedback from long-standing
project developers, and particularly members of the [core team][core]
is a good indication that the RFC is worth pursuing.

[issues]: https://github.com/rust-lang/rfcs/issues
[discuss]: http://discuss.rust-lang.org/
[core]: https://github.com/rust-lang/rust/wiki/Note-core-team

## 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 merged into the RFC repo as a markdown file. At that point the RFC
is 'active' and may be implemented with the goal of eventual inclusion
Expand All @@ -109,18 +140,34 @@ into Rust.
* Fork the RFC repo http://github.com/rust-lang/rfcs
* Copy `0000-template.md` to `text/0000-my-feature.md` (where
'my-feature' is descriptive. don't assign an RFC number yet).
* Fill in the RFC
* Submit a pull request. The pull request is the time to get review of
the design from the larger community.
* During Rust triage, the pull request will either be closed or
assigned a shepherd. The shepherd will help to move the RFC forward,
* 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 disinginuous about the drawbacks or
Copy link

Choose a reason for hiding this comment

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

disingenuous, not disinginuous

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks. Fixed.

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.
* During Rust triage, the pull request will either be closed (for RFCs
that clearly will not be accepted) or assigned a *shepherd*. The
shepherd is a trusted developer who is familiar with the process, who
will help to move the RFC forward, and ensure that the right people
see and review it.
* 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. The shepherd assigned to your RFC should help you get
feedback from Rust developers as well.
* Eventually, somebody on the [core team] will either accept the RFC by
merging the pull request and assigning the RFC a number, at which point
the RFC is 'active', or reject it by closing the pull request.
* The shepherd 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 the larger [weekly meeting]. In
either case a summary from the meeting will be posted back to the RFC
pull request.
* Once both proponents and opponents have clarified and defended
positions and the conversation has settled, the shepherd will take it
to the [core team] for a final decision.
* Eventually, someone from the [core team] will either accept the RFC
by merging the pull request, assigning the RFC a number (corresponding
to the pull request number), at which point the RFC is 'active', or
reject it by closing the pull request.

## The role of the shepherd
[The role of the shepherd]: the-role-of-the-shepherd
Expand All @@ -138,11 +185,12 @@ point where we actually reach a decision.
## 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 Rust repo. An '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.
Once an RFC becomes active then authors may implement it and submit
Copy link
Member

Choose a reason for hiding this comment

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

While we're updating this, it may be worth clarifying if the author of the RFC is expected to implement the feature or not. Maybe there should at least be some understanding of who's going to implement it and when? There are some accepted RFCs that have just been sitting there without an implementation for a while now.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I was considering that, but didn't know quite what to write. It's best if the author is capable of and willing to implement the RFC, but it's not a requirement.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added some text about this.

the feature as a pull request to the Rust 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
Expand All @@ -162,6 +210,23 @@ considered 'complete' and is moved to the 'complete' folder; an RFC
that fails after becoming active is 'inactive' and moves to the
'inactive' folder.

## Reviewing RFC's
[Reviewing RFC's]: #reviewing-rfcs

While the RFC PR is up, the shepherd 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 the larger
[weekly meeting]. In either case a summary from the meeting will be
posted back to the RFC pull request.

The core team makes final decisions about RFCs after the benefits and
drawbacks are well understood. These decisions can be made at any
time, but the core team will regularly issue decisions on at least a
weekly basis. When a decision is made, the RFC PR will either be
merged or closed, in either case with a comment describing the
rationale for the decision. The comment should largely be a summary of
discussion already on the comment thread.

## Implementing an RFC
[Implementing an RFC]: #implementing-an-rfc

Expand All @@ -181,33 +246,6 @@ 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).

## Reviewing RFC's
[Reviewing RFC's]: #reviewing-rfcs

Each week the [core team] will attempt to review some set of open RFC
pull requests. The choice of pull requests to review is largely
driven by an informal estimate of whether its associated comment
thread has reached a steady state (i.e. either died out, or not
showing any sign of providing feedback improvements to the RFC
itself). The list of RFC's up for review is posted a week ahead of
time via standard notification channels (currently the 'rust-dev'
mailing list as well as the http://discuss.rust-lang.org/ discourse
site).

We try to make sure that any RFC that we accept is accepted at the
Tuesday team meeting, with a formal record of discussion regarding
acceptance. We do not accept RFC’s at the Thursday triage meeting.
We may reject RFC’s at either meeting; in other words, the only RFC
activity on Thursdays is closing the ones that have reached a steady
state and that the team agrees we will not be adopting.

At both meetings, we try to only consider RFC’s for which at least a
few participants have read the corresponding discussion thread and are
prepared to represent the viewpoints presented there. One participant
should act as a "shepherd" for the feature. The shepherd need not
*personally* desire the feature; they just need to act to represent
its virtues and the community’s desire for it.

## RFC Postponement
[RFC Postponement]: #rfc-postponement

Expand Down Expand Up @@ -236,3 +274,5 @@ necessary.

[core team]: https://github.com/mozilla/rust/wiki/Note-core-team
[triage process]: https://github.com/rust-lang/rust/wiki/Note-development-policy#milestone-and-priority-nomination-and-triage
[weekly meeting]: https://github.com/rust-lang/meeting-minutes