Many changes, including bug fixes and documentation improvements, can be implemented and reviewed via the normal GitHub pull request workflow.
However, some changes are “substantial”, and we ask that these be put through a bit of a design process and produce a consensus among the React-Spectrum core team.
The “RFC” (request for comments) process is intended to provide a consistent and controlled path for new features and components to enter the project.
You need to follow this process if you intend to make "substantial" changes to the React Spectrum project or its documentation. What constitutes a "substantial" change is evolving based on community norms, but may include the following.
- A new React Spectrum Component (hopefully it already exists in spectrum)
- Any breaking change (like modifying the API of a component)
Some changes do not require an RFC:
- Rephrasing, reorganizing or refactoring
- Additions that strictly improve objective, numerical quality criteria (speedup, better browser support)
- Additions only likely to be noticed by other implementors-of-React-Spectrum, invisible to users-of-React-Spectrum.
In addition to these, the React-Spectrum core team may request an RFC for any other change that it deems "substantial" based on the size or scope of the request.
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.
It's often helpful to get feedback on your concept before diving into the level of API design detail required for an RFC. You may open an issue on this repo to start a high-level discussion, with the goal of eventually formulating an RFC pull request with the specific implementation design.
To submit a new RFC, follow these steps:
- Fork this repo.
- Create a directory inside this
rfcsdirectory. The directory name should begin with the year and include a meaningful description, such asrfcs/2018-cyclebutton-new-component. - Copy the template.md file from this
rfcsdirectory into your newly created subdirectory (such asrfcs/2018-cyclebutton-new-componet/README.md). Be sure to name your fileREADME.mdso it is easily viewable in the GitHub interface. - If you want to include images in your RFC, place them in the same directory as the
README.md. - Fill in the RFC. Please fill in every section in the template with as much detail as possible.
- Submit a pull request to this repo with all of your files.
- You will receive feedback both from the React-Spectrum community and from the React-Spectrum core team. You should be prepared to update your RFC based on this feedback. The goal is to build consensus on the best way to implement the suggested change.
- When all feedback has been incorporated, the React-Spectrum core team will determine whether or not to accept the RFC. RFCs that are accepted will be merged directly into this repo; RFCs that are not accepted will have their pull requests closed without merging.
Once an RFC is merged into this repo, then the authors may implement it and submit a pull request to this repo without opening an issue. Note that the implementation still needs to be reviewed separate from the RFC, so you should expect more feedback and iteration.
If the RFC authors choose not to implement the RFC, then the RFC may be implemented by anyone. There is no guarantee that RFCs not implemented by their author will be implemented by the React-Spectrum core team.
Changes to the design during implementation should be reflected by updating the related RFC. The goal is to have RFCs to look back on to understand the motivation and design of shipped React-Spectrum features.
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.
When a pull request has implemented an RFC, the RFC should be updated with a link to the PR implementing it.
Thanks to the Ember RFC process and ESLint RFC Process for the inspiration for React Spectrum's RFC process.