-
Notifications
You must be signed in to change notification settings - Fork 5.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Adapt Rust's RFC process for Sway (#1)
* Adapt Rust's RFC process for Sway * Update README.md * Update rfcs/0001-rfc-process.md Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com> * Update rfcs/0001-rfc-process.md Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com> * Update rfcs/0001-rfc-process.md Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com> * Update rfcs/0001-rfc-process.md Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com> * Update rfcs/0001-rfc-process.md Co-authored-by: John Adler <adlerjohn@users.noreply.github.com> * Update README * remove invalid italics * Add notes on breaking changes Co-authored-by: Mohammad Fawaz <mohammadfawaz89@gmail.com> Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
- Loading branch information
3 people
authored
Jun 28, 2022
1 parent
8a9e194
commit 413a898
Showing
3 changed files
with
209 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| - 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: [FuelLabs/sway-rfcs#0000](https://github.com/FuelLabs/sway-rfcs/pull/0000) | ||
| - Sway Issue: [FueLabs/sway#0000](https://github.com/FuelLabs/Sway/issues/0000) | ||
|
|
||
| # 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 Sway programmer. That generally means: | ||
|
|
||
| - Introducing new named concepts. | ||
| - Explaining the feature largely in terms of examples. | ||
| - Explaining how Sway programmers should *think* about the feature, and how it should impact the way they use Sway. 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 Sway programmers and new Sway programmers. | ||
| - If this change is breaking, discuss how existing codebases can adapt to this change. | ||
|
|
||
| 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. | ||
|
|
||
| # 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. | ||
| - If this change is breaking, mention the impact of it here and how the breaking change should be managed. | ||
|
|
||
| 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 | ||
| [rationale-and-alternatives]: #rationale-and-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? | ||
| - What is the impact of not doing this? | ||
|
|
||
| # Prior art | ||
| [prior-art]: #prior-art | ||
|
|
||
| Discuss prior art, both the good and the bad, in relation to this proposal. | ||
| A few examples of what this can include are: | ||
|
|
||
| - For language, library, cargo, tools, and compiler proposals: Does this feature exist in other programming languages and what experience have their community had? | ||
| - For community proposals: Is this done by some other community and what were their experiences with it? | ||
| - For other teams: What lessons can we learn from what other communities have done here? | ||
| - Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background. | ||
|
|
||
| This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture. | ||
| If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages. | ||
|
|
||
| Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC. | ||
| Please also take into consideration that rust sometimes intentionally diverges from common language features. | ||
|
|
||
| # Unresolved questions | ||
| [unresolved-questions]: #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? | ||
|
|
||
| # Future possibilities | ||
| [future-possibilities]: #future-possibilities | ||
|
|
||
| Think about what the natural extension and evolution of your proposal would | ||
| be and how it would affect the language and project as a whole in a holistic | ||
| way. Try to use this section as a tool to more fully consider all possible | ||
| interactions with the project and language in your proposal. | ||
| Also consider how this all fits into the roadmap for the project | ||
| and of the relevant sub-team. | ||
|
|
||
| This is also a good place to "dump ideas", if they are out of scope for the | ||
| RFC you are writing but otherwise related. | ||
|
|
||
| If you have tried and cannot think of any future possibilities, | ||
| you may simply state that you cannot think of anything. | ||
|
|
||
| Note that having something written down in the future-possibilities section | ||
| is not a reason to accept the current or a future RFC; such notes should be | ||
| in the section on motivation or rationale in this or subsequent RFCs. | ||
| The section merely provides additional information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,6 @@ | ||
| # sway-rfcs | ||
| # Sway RFCs | ||
|
|
||
|
|
||
|
|
||
| ## Active RFCs | ||
| _None_ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| - Start Date: 2022-06-15 | ||
| - RFC PR: [FuelLabs/sway#1](https://github.com/FuelLabs/sway-rfcs/pull/1) | ||
|
|
||
| This RFC process is inspired by, and mostly copied from, Rust's RFC process. | ||
| See [here](https://github.com/rust-lang/rfcs/blob/master/text/0002-rfc-process.md) | ||
| for Rust's version of this. | ||
|
|
||
| Rust's RFC process has proven efficiency that we'd like to emulate. | ||
|
|
||
| # Summary | ||
|
|
||
| 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. | ||
|
|
||
| # Motivation | ||
|
|
||
| The freewheeling way that we add new features to Sway has been good for | ||
| early development, but for Sway to become a mature platform we need to | ||
| develop some more self-discipline when it comes to changing the system. | ||
| This is a proposal for a more principled RFC process to make it | ||
| a more integral part of the overall development process, and one that is | ||
| followed consistently to introduce features to Sway. | ||
|
|
||
| # Detailed design | ||
|
|
||
| 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 Sway | ||
| community and the [core team]. | ||
|
|
||
| ## When you need to follow this process | ||
|
|
||
| You need to follow this process if you intend to make "substantial" | ||
| changes to the Sway distribution. What constitutes a "substantial" | ||
| change is evolving based on community norms, but may include the following. | ||
|
|
||
| - Any semantic or syntactic change to the language that is not a bugfix. | ||
| - Removing language features, including those that are feature-gated. | ||
| - Changes to the interface between the compiler and libraries, | ||
| including lang items and intrinsics. | ||
| - Eventually, when we reach stdlib maturity, we will want to use RFCs for | ||
| stdlib design as well. | ||
|
|
||
| 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-Sway, | ||
| invisible to users-of-sway. | ||
|
|
||
| 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. | ||
|
|
||
| ## What the process is | ||
|
|
||
| In short, to get a major feature added to Sway, 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 | ||
| into Sway. | ||
|
|
||
| * Fork the RFC repo https://github.com/FuelLabs/sway-rfcs (or make a branch if you are core-team). | ||
| * Copy `0000-template.md` to `rfcs/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. | ||
| * 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. | ||
|
|
||
| Eventually, somebody on the [core team] will either accept the RFC by | ||
| merging the pull request, at which point the RFC is 'active', or | ||
| reject it by closing the pull request. | ||
|
|
||
| Whomever merges the RFC should do the following: | ||
|
|
||
| * Assign an id, using the PR number of the RFC pull request. (If the RFC | ||
| has multiple pull requests associated with it, choose one PR number, | ||
| preferably the minimal one.) | ||
| * Add the file in the `rfcs/` directory. | ||
| * Create a corresponding issue on [Sway repo](https://github.com/FuelLabs/sway). | ||
| * Fill in the remaining metadata in the RFC header, including links for | ||
| the original pull request(s) and the newly created Sway issue. | ||
| * Add an entry in the [Active RFC List] of the root `README.md`. | ||
| * Commit everything. | ||
|
|
||
| Once an RFC becomes active then authors may implement it and submit the | ||
| feature as a pull request to the Sway 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. | ||
|
|
||
| Modifications to active RFC's can be done in followup PR's. An RFC that | ||
| makes it through the entire process to implementation is considered | ||
| 'complete' and is removed from the [Active RFC List]; an RFC that fails | ||
| after becoming active is 'inactive' and moves to the 'inactive' folder. | ||
|
|
||
| [core team]: https://github.com/orgs/FuelLabs/teams/sway-compiler |