mirror of https://github.com/rust-lang/rfcs
Merge branch 'master' of github.com:rust-lang/rfcs
This commit is contained in:
parent
d8321d8077
commit
7fc338e5b4
171
README.md
171
README.md
|
@ -8,7 +8,7 @@ implemented and reviewed via the normal GitHub pull request workflow.
|
||||||
|
|
||||||
Some changes though are "substantial", and we ask that these be put
|
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 Rust
|
through a bit of a design process and produce a consensus among the Rust
|
||||||
community and the [core team].
|
community and the [sub-team]s.
|
||||||
|
|
||||||
The "RFC" (request for comments) process is intended to provide a
|
The "RFC" (request for comments) process is intended to provide a
|
||||||
consistent and controlled path for new features to enter the language
|
consistent and controlled path for new features to enter the language
|
||||||
|
@ -80,19 +80,21 @@ the direction the language is evolving in.
|
||||||
* [RFC Postponement]
|
* [RFC Postponement]
|
||||||
* [Help this is all too informal!]
|
* [Help this is all too informal!]
|
||||||
|
|
||||||
|
|
||||||
## When you need to follow this process
|
## When you need to follow this process
|
||||||
[When you need to follow this process]: #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"
|
You need to follow this process if you intend to make "substantial" changes to
|
||||||
changes to Rust, Cargo, Crates.io, or the RFC process itself. What constitutes
|
Rust, Cargo, Crates.io, or the RFC process itself. What constitutes a
|
||||||
a "substantial" change is evolving based on community norms, but may include
|
"substantial" change is evolving based on community norms and varies depending
|
||||||
the following.
|
on what part of the ecosystem you are proposing to change, but may include the
|
||||||
|
following.
|
||||||
|
|
||||||
- Any semantic or syntactic change to the language that is not a bugfix.
|
- Any semantic or syntactic change to the language that is not a bugfix.
|
||||||
- Removing language features, including those that are feature-gated.
|
- Removing language features, including those that are feature-gated.
|
||||||
- Changes to the interface between the compiler and libraries,
|
- Changes to the interface between the compiler and libraries, including lang
|
||||||
including lang items and intrinsics.
|
items and intrinsics.
|
||||||
- Additions to `std`
|
- Additions to `std`.
|
||||||
|
|
||||||
Some changes do not require an RFC:
|
Some changes do not require an RFC:
|
||||||
|
|
||||||
|
@ -108,6 +110,15 @@ 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
|
through the RFC process, it may be closed with a polite request to
|
||||||
submit an RFC first.
|
submit an RFC first.
|
||||||
|
|
||||||
|
For more details on when an RFC is required, please see the following specific
|
||||||
|
guidelines, these correspond with some of the Rust community's
|
||||||
|
[sub-teams](http://www.rust-lang.org/team.html):
|
||||||
|
|
||||||
|
* [language changes](lang_changes.md),
|
||||||
|
* [library changes](libs_changes.md),
|
||||||
|
* [compiler changes](compiler_changes.md).
|
||||||
|
|
||||||
|
|
||||||
## Before creating an RFC
|
## Before creating an RFC
|
||||||
[Before creating an RFC]: #before-creating-an-rfc
|
[Before creating an RFC]: #before-creating-an-rfc
|
||||||
|
|
||||||
|
@ -130,12 +141,12 @@ on the [RFC issue tracker][issues], and occasionally posting
|
||||||
review.
|
review.
|
||||||
|
|
||||||
As a rule of thumb, receiving encouraging feedback from long-standing
|
As a rule of thumb, receiving encouraging feedback from long-standing
|
||||||
project developers, and particularly members of the [core team][core]
|
project developers, and particularly members of the relevant [sub-team]
|
||||||
is a good indication that the RFC is worth pursuing.
|
is a good indication that the RFC is worth pursuing.
|
||||||
|
|
||||||
[issues]: https://github.com/rust-lang/rfcs/issues
|
[issues]: https://github.com/rust-lang/rfcs/issues
|
||||||
[discuss]: http://discuss.rust-lang.org/
|
[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]: #what-the-process-is
|
[What the process is]: #what-the-process-is
|
||||||
|
@ -146,49 +157,57 @@ is 'active' and may be implemented with the goal of eventual inclusion
|
||||||
into Rust.
|
into Rust.
|
||||||
|
|
||||||
* Fork the RFC repo http://github.com/rust-lang/rfcs
|
* Fork the RFC repo http://github.com/rust-lang/rfcs
|
||||||
* Copy `0000-template.md` to `text/0000-my-feature.md` (where
|
* Copy `0000-template.md` to `text/0000-my-feature.md` (where 'my-feature' is
|
||||||
'my-feature' is descriptive. don't assign an RFC number yet).
|
descriptive. don't assign an RFC number yet).
|
||||||
* Fill in the RFC. Put care into the details: RFCs that do not
|
* Fill in the RFC. Put care into the details: RFCs that do not present
|
||||||
present convincing motivation, demonstrate understanding of the
|
convincing motivation, demonstrate understanding of the impact of the design, or
|
||||||
impact of the design, or are disingenuous about the drawbacks or
|
are disingenuous about the drawbacks or alternatives tend to be poorly-received.
|
||||||
alternatives tend to be poorly-received.
|
* Submit a pull request. As a pull request the RFC will receive design feedback
|
||||||
* Submit a pull request. As a pull request the RFC will receive design
|
from the larger community, and the author should be prepared to revise it in
|
||||||
feedback from the larger community, and the author should be prepared
|
response.
|
||||||
to revise it in response.
|
* Each pull request will be labeled with the most relevant [sub-team].
|
||||||
* During Rust triage, the pull request will either be closed (for RFCs
|
* Each sub-team triages its RFC PRs. The sub-team will will either close the PR
|
||||||
that clearly will not be accepted) or assigned a *shepherd*. The
|
(for RFCs that clearly will not be accepted) or assign it a *shepherd*. The
|
||||||
shepherd is a trusted developer who is familiar with the process, who
|
shepherd is a trusted developer who is familiar with the RFC process, who will
|
||||||
will help to move the RFC forward, and ensure that the right people
|
help to move the RFC forward, and ensure that the right people see and review
|
||||||
see and review it.
|
it.
|
||||||
* Build consensus and integrate feedback. RFCs that have broad support
|
* Build consensus and integrate feedback. RFCs that have broad support are much
|
||||||
are much more likely to make progress than those that don't receive
|
more likely to make progress than those that don't receive any comments. The
|
||||||
any comments. The shepherd assigned to your RFC should help you get
|
shepherd assigned to your RFC should help you get feedback from Rust developers
|
||||||
feedback from Rust developers as well.
|
as well.
|
||||||
* The shepherd may schedule meetings with the author and/or relevant
|
* The shepherd may schedule meetings with the author and/or relevant
|
||||||
stakeholders to discuss the issues in greater detail, and in some
|
stakeholders to discuss the issues in greater detail.
|
||||||
cases the topic may be discussed at the larger [weekly meeting]. In
|
* The sub-team will discuss the RFC PR, as much as possible in the comment
|
||||||
either case a summary from the meeting will be posted back to the RFC
|
thread of the PR itself. Offline discussion will be summarized on the PR comment
|
||||||
pull request.
|
thread.
|
||||||
* Once both proponents and opponents have clarified and defended
|
* Once both proponents and opponents have clarified and defended positions and
|
||||||
positions and the conversation has settled, the shepherd will take it
|
the conversation has settled, the RFC will enter its *final comment period*
|
||||||
to the [core team] for a final decision.
|
(FCP). This is a final opportunity for the community to comment on the PR and is
|
||||||
* Eventually, someone from the [core team] will either accept the RFC
|
a reminder for all members of the sub-team to be aware of the RFC.
|
||||||
by merging the pull request, assigning the RFC a number (corresponding
|
* The FCP lasts one week. It may be extended if consensus between sub-team
|
||||||
to the pull request number), at which point the RFC is 'active', or
|
members cannot be reached. At the end of the FCP, the [sub-team] will either
|
||||||
reject it by closing the pull request.
|
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. How exactly the sub-team decide on an
|
||||||
|
RFC is up to the sub-team.
|
||||||
|
|
||||||
|
|
||||||
## The role of the shepherd
|
## The role of the shepherd
|
||||||
[The role of the shepherd]: #the-role-of-the-shepherd
|
[The role of the shepherd]: #the-role-of-the-shepherd
|
||||||
|
|
||||||
During triage, every RFC will either be closed or assigned a shepherd.
|
During triage, every RFC will either be closed or assigned a shepherd from the
|
||||||
The role of the shepherd is to move the RFC through the process. This
|
relevant sub-team. The role of the shepherd is to move the RFC through the
|
||||||
starts with simply reading the RFC in detail and providing initial
|
process. This starts with simply reading the RFC in detail and providing initial
|
||||||
feedback. The shepherd should also solicit feedback from people who
|
feedback. The shepherd should also solicit feedback from people who are likely
|
||||||
are likely to have strong opinions about the RFC. Finally, when this
|
to have strong opinions about the RFC. When this feedback has been incorporated
|
||||||
feedback has been incorporated and the RFC seems to be in a steady
|
and the RFC seems to be in a steady state, the shepherd and/or sub-team leader
|
||||||
state, the shepherd will bring it to the meeting. In general, the idea
|
will announce an FCP. In general, the idea here is to "front-load" as much of
|
||||||
here is to "front-load" as much of the feedback as possible before the
|
the feedback as possible before the point where we actually reach a decision -
|
||||||
point where we actually reach a decision.
|
by the end of the FCP, the decision on whether or not to accept the RFC should
|
||||||
|
usually be obvious from the RFC discussion thread. On occasion, there may not be
|
||||||
|
consensus but discussion has stalled. In this case, the relevant team will make
|
||||||
|
a decision.
|
||||||
|
|
||||||
|
|
||||||
## The RFC life-cycle
|
## The RFC life-cycle
|
||||||
[The RFC life-cycle]: #the-rfc-life-cycle
|
[The RFC life-cycle]: #the-rfc-life-cycle
|
||||||
|
@ -210,35 +229,36 @@ through to completion: authors should not expect that other project
|
||||||
developers will take on responsibility for implementing their accepted
|
developers will take on responsibility for implementing their accepted
|
||||||
feature.
|
feature.
|
||||||
|
|
||||||
Modifications to active RFC's can be done in followup PR's. We strive
|
Modifications to active RFC's can be done in follow-up PR's. We strive
|
||||||
to write each RFC in a manner that it will reflect the final design of
|
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
|
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
|
every merged RFC to actually reflect what the end result will be at
|
||||||
the time of the next major release; therefore we try to keep each RFC
|
the time of the next major release.
|
||||||
document somewhat in sync with the language feature as planned,
|
|
||||||
tracking such changes via followup pull requests to the document.
|
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 sub-team to decide. There are some more
|
||||||
|
specific guidelines in the sub-team RFC guidelines for the [language](lang_changes.md),
|
||||||
|
[libraries](libs_changes.md), and [compiler](compiler_changes.md).
|
||||||
|
|
||||||
An RFC that makes it through the entire process to implementation is
|
|
||||||
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 RFC's]: #reviewing-rfcs
|
[Reviewing RFC's]: #reviewing-rfcs
|
||||||
|
|
||||||
While the RFC PR is up, the shepherd may schedule meetings with the
|
While the RFC PR is up, the shepherd may schedule meetings with the
|
||||||
author and/or relevant stakeholders to discuss the issues in greater
|
author and/or relevant stakeholders to discuss the issues in greater
|
||||||
detail, and in some cases the topic may be discussed at the larger
|
detail, and in some cases the topic may be discussed at a sub-team
|
||||||
[weekly meeting]. In either case a summary from the meeting will be
|
meeting. In either case a summary from the meeting will be
|
||||||
posted back to the RFC pull request.
|
posted back to the RFC pull request.
|
||||||
|
|
||||||
The core team makes final decisions about RFCs after the benefits and
|
A sub-team makes final decisions about RFCs after the benefits and drawbacks are
|
||||||
drawbacks are well understood. These decisions can be made at any
|
well understood. These decisions can be made at any time, but the sub-team will
|
||||||
time, but the core team will regularly issue decisions on at least a
|
regularly issue decisions. When a decision is made, the RFC PR will either be
|
||||||
weekly basis. When a decision is made, the RFC PR will either be
|
merged or closed. In either case, if the reasoning is not clear from the
|
||||||
merged or closed, in either case with a comment describing the
|
discussion in thread, the sub-team will add a comment describing the rationale
|
||||||
rationale for the decision. The comment should largely be a summary of
|
for the decision.
|
||||||
discussion already on the comment thread.
|
|
||||||
|
|
||||||
## Implementing an RFC
|
## Implementing an RFC
|
||||||
[Implementing an RFC]: #implementing-an-rfc
|
[Implementing an RFC]: #implementing-an-rfc
|
||||||
|
@ -248,7 +268,7 @@ implemented right away. Other accepted RFC's can represent features
|
||||||
that can wait until some arbitrary developer feels like doing the
|
that can wait until some arbitrary developer feels like doing the
|
||||||
work. Every accepted RFC has an associated issue tracking its
|
work. Every accepted RFC has an associated issue tracking its
|
||||||
implementation in the Rust repository; thus that associated issue can
|
implementation in the Rust repository; thus that associated issue can
|
||||||
be assigned a priority via the [triage process] that the team uses for
|
be assigned a priority via the triage process that the team uses for
|
||||||
all issues in the Rust repository.
|
all issues in the Rust repository.
|
||||||
|
|
||||||
The author of an RFC is not obligated to implement it. Of course, the
|
The author of an RFC is not obligated to implement it. Of course, the
|
||||||
|
@ -259,15 +279,18 @@ If you are interested in working on the implementation for an 'active'
|
||||||
RFC, but cannot determine if someone else is already working on it,
|
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).
|
feel free to ask (e.g. by leaving a comment on the associated issue).
|
||||||
|
|
||||||
|
|
||||||
## RFC Postponement
|
## RFC Postponement
|
||||||
[RFC Postponement]: #rfc-postponement
|
[RFC Postponement]: #rfc-postponement
|
||||||
|
|
||||||
Some RFC pull requests are tagged with the 'postponed' label when they
|
Some RFC pull requests are tagged with the 'postponed' label when they are
|
||||||
are closed (as part of the rejection process). An RFC closed with
|
closed (as part of the rejection process). An RFC closed with “postponed” is
|
||||||
“postponed” is marked as such because we want neither to think about
|
marked as such because we want neither to think about evaluating the proposal
|
||||||
evaluating the proposal nor about implementing the described feature
|
nor about implementing the described feature until some time in the future, and
|
||||||
until after the next major release, and we believe that we can afford
|
we believe that we can afford to wait until then to do so. Historically,
|
||||||
to wait until then to do so.
|
"postponed" was used to postpone features until after 1.0. Postponed PRs 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 sub-team.
|
||||||
|
|
||||||
Usually an RFC pull request marked as “postponed” has already passed
|
Usually an RFC pull request marked as “postponed” has already passed
|
||||||
an informal first round of evaluation, namely the round of “do we
|
an informal first round of evaluation, namely the round of “do we
|
||||||
|
@ -285,6 +308,4 @@ present circumstances. As usual, we are trying to let the process be
|
||||||
driven by consensus and community norms, not impose more structure than
|
driven by consensus and community norms, not impose more structure than
|
||||||
necessary.
|
necessary.
|
||||||
|
|
||||||
[core team]: https://github.com/mozilla/rust/wiki/Note-core-team
|
[sub-team]: http://www.rust-lang.org/team.html
|
||||||
[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
|
|
||||||
|
|
|
@ -0,0 +1,52 @@
|
||||||
|
# RFC policy - the compiler
|
||||||
|
|
||||||
|
We have not previously had an RFC system for compiler changes, so policy here is
|
||||||
|
likely to change as we get the hang of things. We don't want to slow down most
|
||||||
|
compiler development, but on the other hand we do want to do more design work
|
||||||
|
ahead of time on large additions and refactorings.
|
||||||
|
|
||||||
|
Compiler RFCs will be managed by the compiler sub-team, and tagged `T-compiler`.
|
||||||
|
The compiler sub-team will do an initial triage of new PRs within a week of
|
||||||
|
submission. The result of triage will either be that the PR is assigned to a
|
||||||
|
member of the sub-team for shepherding, the PR is closed because the sub-team
|
||||||
|
believe it should be done without an RFC, or closed because the sub-team feel it
|
||||||
|
should clearly not be done and further discussion is not necessary. We'll follow
|
||||||
|
the standard procedure for shepherding, final comment period, etc.
|
||||||
|
|
||||||
|
Where there is significant design work for the implementation of a language
|
||||||
|
feature, the preferred workflow is to submit two RFCs - one for the language
|
||||||
|
design and one for the implementation design. The implementation RFC may be
|
||||||
|
submitted later if there is scope for large changes to the language RFC.
|
||||||
|
|
||||||
|
|
||||||
|
## Changes which need an RFC
|
||||||
|
|
||||||
|
* Large refactorings or redesigns of the compiler
|
||||||
|
* Changing the API presented to syntax extensions or other compiler plugins in
|
||||||
|
non-trivial ways
|
||||||
|
* Adding, removing, or changing a stable compiler flag
|
||||||
|
* The implementation of new language features where there is significant change
|
||||||
|
or addition to the compiler. There is obviously some room for interpretation
|
||||||
|
about what consitutes a "significant" change and how much detail the
|
||||||
|
implementation RFC needs. For guidance, [associated items](text/0195-associated-items.md)
|
||||||
|
and [UFCS](text/0132-ufcs.md) would clearly need an implementation RFC,
|
||||||
|
[type ascription](text/0803-type-ascription.md) and
|
||||||
|
[lifetime elision](text/0141-lifetime-elision.md) would not.
|
||||||
|
* Any other change which causes backwards incompatible changes to stable
|
||||||
|
behaviour of the compiler, language, or libraries
|
||||||
|
|
||||||
|
|
||||||
|
## Changes which don't need an RFC
|
||||||
|
|
||||||
|
* Bug fixes, improved error messages, etc.
|
||||||
|
* Minor refactoring/tidying up
|
||||||
|
* Implmenting language features which have an accepted RFC, where the
|
||||||
|
implementation does not significantly change the compiler or require
|
||||||
|
significant new design work
|
||||||
|
* Adding unstable API for tools (note that all compiler API is currently unstable)
|
||||||
|
* Adding, removing, or changing an unstable compiler flag (if the compiler flag
|
||||||
|
is widely used there should be at least some discussion on discuss, or an RFC
|
||||||
|
in some cases)
|
||||||
|
|
||||||
|
If in doubt it is probably best to just announce the change you want to make to
|
||||||
|
the compiler subteam on discuss or IRC, and see if anyone feels it needs an RFC.
|
|
@ -0,0 +1,36 @@
|
||||||
|
# RFC policy - language design
|
||||||
|
|
||||||
|
Pretty much every change to the language needs an RFC.
|
||||||
|
|
||||||
|
Language RFCs are managed by the language sub-team, and tagged `T-lang`. The
|
||||||
|
language sub-team will do an initial triage of new PRs within a week of
|
||||||
|
submission. The result of triage will either be that the PR is assigned to a
|
||||||
|
member of the sub-team for shepherding, the PR is closed as postponed because
|
||||||
|
the subteam believe it might be a good idea, but is not currently aligned with
|
||||||
|
Rust's priorities, or the PR is closed because the sub-team feel it should
|
||||||
|
clearly not be done and further discussion is not necessary. In the latter two
|
||||||
|
cases, the sub-team will give a detailed explanation. We'll follow the standard
|
||||||
|
procedure for shepherding, final comment period, etc.
|
||||||
|
|
||||||
|
|
||||||
|
## Amendments
|
||||||
|
|
||||||
|
Sometimes in the implementation of an RFC, changes are required. In general
|
||||||
|
these don't require an RFC as long as they are very minor and in the spirit of
|
||||||
|
the accepted RFC (essentially bug fixes). In this case implementers should
|
||||||
|
submit an RFC PR which amends the accepted RFC with the new details. Although
|
||||||
|
the RFC repository is not intended as a reference manual, it is preferred that
|
||||||
|
RFCs do reflect what was actually implemented. Amendment RFCs will go through
|
||||||
|
the same process as regular RFCs, but should be less controversial and thus
|
||||||
|
should move more quickly.
|
||||||
|
|
||||||
|
When a change is more dramatic, it is better to create a new RFC. The RFC should
|
||||||
|
be standalone and reference the original, rather than modifying the existing
|
||||||
|
RFC. You should add a comment to the original RFC with referencing the new RFC
|
||||||
|
as part of the PR.
|
||||||
|
|
||||||
|
Obviously there is some scope for judgment here. As a guideline, if a change
|
||||||
|
affects more than one part of the RFC (i.e., is a non-local change), affects the
|
||||||
|
applicability of the RFC to its motivating use cases, or there are multiple
|
||||||
|
possible new solutions, then the feature is probably not 'minor' and should get
|
||||||
|
a new RFC.
|
|
@ -0,0 +1,114 @@
|
||||||
|
# RFC guidelines - libraries sub-team
|
||||||
|
|
||||||
|
# Motivation
|
||||||
|
|
||||||
|
* RFCs are heavyweight:
|
||||||
|
* RFCs generally take at minimum 2 weeks from posting to land. In
|
||||||
|
practice it can be more on the order of months for particularly
|
||||||
|
controversial changes.
|
||||||
|
* RFCs are a lot of effort to write; especially for non-native speakers or
|
||||||
|
for members of the community whose strengths are more technical than literary.
|
||||||
|
* RFCs may involve pre-RFCs and several rewrites to accommodate feedback.
|
||||||
|
* RFCs require a dedicated shepherd to herd the community and author towards
|
||||||
|
consensus.
|
||||||
|
* RFCs require review from a majority of the subteam, as well as an official
|
||||||
|
vote.
|
||||||
|
* RFCs can't be downgraded based on their complexity. Full process always applies.
|
||||||
|
Easy RFCs may certainly land faster, though.
|
||||||
|
* RFCs can be very abstract and hard to grok the consequences of (no implementation).
|
||||||
|
|
||||||
|
* PRs are low *overhead* but potentially expensive nonetheless:
|
||||||
|
* Easy PRs can get insta-merged by any rust-lang contributor.
|
||||||
|
* Harder PRs can be easily escalated. You can ping subject-matter experts for second
|
||||||
|
opinions. Ping the whole team!
|
||||||
|
* Easier to grok the full consequences. Lots of tests and Crater to save the day.
|
||||||
|
* PRs can be accepted optimistically with bors, buildbot, and the trains to guard
|
||||||
|
us from major mistakes making it into stable. The size of the nightly community
|
||||||
|
at this point in time can still mean major community breakage regardless of trains,
|
||||||
|
however.
|
||||||
|
* HOWEVER: Big PRs can be a lot of work to make only to have that work rejected for
|
||||||
|
details that could have been hashed out first.
|
||||||
|
|
||||||
|
* RFCs are *only* meaningful if a significant and diverse portion of the
|
||||||
|
community actively participates in them. The official teams are not
|
||||||
|
sufficiently diverse to establish meaningful community consensus by agreeing
|
||||||
|
amongst themselves.
|
||||||
|
|
||||||
|
* If there are *tons* of RFCs -- especially trivial ones -- people are less
|
||||||
|
likely to engage with them. Official team members are super busy. Domain experts
|
||||||
|
and industry professionals are super busy *and* have no responsibility to engage
|
||||||
|
in RFCs. Since these are *exactly* the most important people to get involved in
|
||||||
|
the RFC process, it is important that we be maximally friendly towards their
|
||||||
|
needs.
|
||||||
|
|
||||||
|
|
||||||
|
# Is an RFC required?
|
||||||
|
|
||||||
|
The overarching philosophy is: *do whatever is easiest*. If an RFC
|
||||||
|
would be less work than an implementation, that's a good sign that an RFC is
|
||||||
|
necessary. That said, if you anticipate controversy, you might want to short-circuit
|
||||||
|
straight to an RFC. For instance new APIs almost certainly merit an RFC. Especially
|
||||||
|
as `std` has become more conservative in favour of the much more agile cargoverse.
|
||||||
|
|
||||||
|
* **Submit a PR** if the change is a:
|
||||||
|
* Bugfix
|
||||||
|
* Docfix
|
||||||
|
* Obvious API hole patch, such as adding an API from one type to a symmetric type.
|
||||||
|
e.g. `Vec<T> -> Box<[T]>` clearly motivates adding `String -> Box<str>`
|
||||||
|
* Minor tweak to an unstable API (renaming, generalizing)
|
||||||
|
* Implementing an "obvious" trait like Clone/Debug/etc
|
||||||
|
* **Submit an RFC** if the change is a:
|
||||||
|
* New API
|
||||||
|
* Semantic Change to a stable API
|
||||||
|
* Generalization of a stable API (e.g. how we added Pattern or Borrow)
|
||||||
|
* Deprecation of a stable API
|
||||||
|
* Nontrivial trait impl (because all trait impls are insta-stable)
|
||||||
|
* **Do the easier thing** if uncertain. (choosing a path is not final)
|
||||||
|
|
||||||
|
|
||||||
|
# Non-RFC process
|
||||||
|
|
||||||
|
* A (non-RFC) PR is likely to be **closed** if clearly not acceptable:
|
||||||
|
* Disproportionate breaking change (small inference breakage may be acceptable)
|
||||||
|
* Unsound
|
||||||
|
* Doesn't fit our general design philosophy around the problem
|
||||||
|
* Better as a crate
|
||||||
|
* Too marginal for std
|
||||||
|
* Significant implementation problems
|
||||||
|
|
||||||
|
* A PR may also be closed because an RFC is approriate.
|
||||||
|
|
||||||
|
* A (non-RFC) PR may be **merged as unstable**. In this case, the feature
|
||||||
|
should have a fresh feature gate and an associated tracking issue for
|
||||||
|
stabilisation. Note that trait impls and docs are insta-stable and thus have no
|
||||||
|
tracking issue. This may imply requiring a higher level of scrutiny for such
|
||||||
|
changes.
|
||||||
|
|
||||||
|
However, an accepted RFC is not a rubber-stamp for merging an implementation PR.
|
||||||
|
Nor must an implementation PR perfectly match the RFC text. Implementation details
|
||||||
|
may merit deviations, though obviously they should be justified. The RFC may be
|
||||||
|
amended if deviations are substantial, but are not generally necessary. RFCs should
|
||||||
|
favour immutability. The RFC + Issue + PR should form a total explanation of the
|
||||||
|
current implementation.
|
||||||
|
|
||||||
|
* Once something has been merged as unstable, a shepherd should be assigned
|
||||||
|
to promote and obtain feedback on the design.
|
||||||
|
|
||||||
|
* Every time a release cycle ends, the libs teams assesses the current unstable
|
||||||
|
APIs and selects some number of them for potential stabilization during the
|
||||||
|
next cycle. These are announced for FCP at the beginning of the cycle, and
|
||||||
|
(possibly) stabilized just before the beta is cut.
|
||||||
|
|
||||||
|
* After the final comment period, an API should ideally take one of two paths:
|
||||||
|
* **Stabilize** if the change is desired, and consensus is reached
|
||||||
|
* **Deprecate** is the change is undesired, and consensus is reached
|
||||||
|
* **Extend the FCP** is the change cannot meet consensus
|
||||||
|
* If consensus *still* can't be reached, consider requiring a new RFC or
|
||||||
|
just deprecating as "too controversial for std".
|
||||||
|
|
||||||
|
* If any problems are found with a newly stabilized API during its beta period,
|
||||||
|
*strongly* favour reverting stability in order to prevent stabilizing a bad
|
||||||
|
API. Due to the speed of the trains, this is not a serious delay (~2-3 months
|
||||||
|
if it's not a major problem).
|
||||||
|
|
||||||
|
|
|
@ -125,10 +125,15 @@ The error conditions that can arise, and their defined results, are as
|
||||||
follows. The intention is that the defined results are the same as the
|
follows. The intention is that the defined results are the same as the
|
||||||
defined results today. The only change is that now a panic may result.
|
defined results today. The only change is that now a panic may result.
|
||||||
|
|
||||||
- The operations `+`, `-`, `*`, `/`, `%` can underflow and
|
- The operations `+`, `-`, `*`, can underflow and overflow. When checking is
|
||||||
overflow.
|
enabled this will panic. When checking is disabled this will two's complement
|
||||||
- Shift operations (`<<`, `>>`) can shift a value of width `N` by more
|
wrap.
|
||||||
than `N` bits.
|
- The operations `/`, `%` for the arguments `INT_MIN` and `-1`
|
||||||
|
will unconditionally panic. This is unconditional for legacy reasons.
|
||||||
|
- Shift operations (`<<`, `>>`) on a value of with `N` can be passed a shift value
|
||||||
|
>= `N`. It is unclear what behaviour should result from this, so the shift value
|
||||||
|
is unconditionally masked to be modulo `N` to ensure that the argument is always
|
||||||
|
in range.
|
||||||
|
|
||||||
## Enabling overflow checking
|
## Enabling overflow checking
|
||||||
|
|
||||||
|
@ -145,7 +150,7 @@ potential overflow (and, in particular, for code where overflow is
|
||||||
expected and normal, they will be immediately guided to use the
|
expected and normal, they will be immediately guided to use the
|
||||||
wrapping methods introduced below). However, because these checks will
|
wrapping methods introduced below). However, because these checks will
|
||||||
be compiled out whenever an optimized build is produced, final code
|
be compiled out whenever an optimized build is produced, final code
|
||||||
wilil not pay a performance penalty.
|
will not pay a performance penalty.
|
||||||
|
|
||||||
In the future, we may add additional means to control when overflow is
|
In the future, we may add additional means to control when overflow is
|
||||||
checked, such as scoped attributes or a global, independent
|
checked, such as scoped attributes or a global, independent
|
||||||
|
@ -451,17 +456,7 @@ were:
|
||||||
|
|
||||||
# Unresolved questions
|
# Unresolved questions
|
||||||
|
|
||||||
The C semantics of wrapping operations in some cases are undefined:
|
None today (see Updates section below).
|
||||||
|
|
||||||
- `INT_MIN / -1`, `INT_MIN % -1`
|
|
||||||
- Shifts by an excessive number of bits
|
|
||||||
|
|
||||||
This RFC takes no position on the correct semantics of these
|
|
||||||
operations, simply preserving the existing semantics. However, it may
|
|
||||||
be worth trying to define the wrapping semantics of these operations
|
|
||||||
in a portable way, even if that implies some runtime cost. Since these
|
|
||||||
are all error conditions, this is an orthogonal topic to the matter of
|
|
||||||
overflow.
|
|
||||||
|
|
||||||
# Future work
|
# Future work
|
||||||
|
|
||||||
|
@ -491,6 +486,10 @@ Since it was accepted, the RFC has been updated as follows:
|
||||||
2. `as` was changed to restore the behavior before the RFC (that is,
|
2. `as` was changed to restore the behavior before the RFC (that is,
|
||||||
it truncates to the target bitwidth and reinterprets the highest
|
it truncates to the target bitwidth and reinterprets the highest
|
||||||
order bit, a.k.a. sign-bit, as necessary, as a C cast would).
|
order bit, a.k.a. sign-bit, as necessary, as a C cast would).
|
||||||
|
3. Shifts were specified to mask off the bits of over-long shifts.
|
||||||
|
4. Overflow was specified to be two's complement wrapping (this was mostly
|
||||||
|
a clarification).
|
||||||
|
5. `INT_MIN / -1` and `INT_MIN % -1` panics.
|
||||||
|
|
||||||
# Acknowledgements and further reading
|
# Acknowledgements and further reading
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue