The RFC ("request for comments") process is how Ember designs and achieves consensus on "substantial" proposed changes.
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 Ember core teams.
The process is intended to provide a consistent and controlled path for new features and changes to enter the framework. RFCs can be created by any member of the community.
This site shows the current state and text of all RFCs in Accepted or later stages.
New proposals for changes are submitted as pull requests to this repo using one of the RFC templates, depending on what the RFC is proposing. The newly opened RFC is in the Proposed stage. The RFC is then reviewed and commented upon by core team members and the community. The core teams may move the RFC to the Exploring stage via a label if they believe the RFC is worth exploring further. From there, with refinement, community consensus, and agreement by the relevant core teams, the RFC enters a Final Comment Period (FCP). If that period is successful, with no new unaddressed concerns raised, the RFC is merged and is now in the Accepted stage.
An RFC that does not achieve consensus to be accepted may enter a Final Comment Period to move the RFC to the Closed stage.
Once the RFC is accepted, a draft pull request is automatically opened to advance the RFC to the Ready for Release stage. This pull request has a template that outlines what is necessary to merge the RFC into this stage. This pull request is where the community can track the progress of the implementation of the RFC. Once the criteria to move to Ready for Release are met, including commitment of the team to the feature's stability, the PR to advance may be merged after a Final Comment Period. Each core team needs to review the PR and approve it before the end of the FCP. If the FCP is successful, the RFC is merged and becomes Ready for Release.
Once the RFC is merged as Ready for Release, a pull request is automatically opened to advance the RFC to the Released stage. This pull request has a template that outlines what is necessary to merge the RFC into this stage. The pull request is merged when those requirements are met and the relevant team has consensus that the RFC has been Released. No FCP is required for this stage.
Once the RFC is merged as Released, a pull request is automatically opened to advance the RFC to the Recommended stage. This pull request has a template that outlines what is necessary to merge the RFC into this stage and can be used for community coordination. This advancement requires a Final Comment Period to merge.
At this point, the RFC is Recommended and complete.
RFCs that have been merged to the repo can also move to the Discontinued stage at any point via a pull request. This is done when the RFC is no longer relevant or the feature is no longer supported.
Read more about the RFC Stages.
| Stage | Description | Requires FCP to enter? |
|---|---|---|
| 0 - Proposed | A proposal for a change to Ember or its processes that is offered for community and team evaluation. | no |
| 1 - Exploring | An RFC deemed worth pursuing but in need of refinement. | no |
| 2 - Accepted | A fully specified RFC. Waiting for or in the process of implementation. | yes |
| 3 - Ready for Release | The implementation of the RFC is complete, including learning materials. | yes |
| 4 - Released | The work is published. If it is codebase-related work, it is in a stable version of the relevant package(s). | no |
| 5 - Recommended | The feature/resource is recommended for general use. | yes |
There are two additional statuses for RFCs that will not move forward:
Proposed RFCs are opened as pull requests to the RFC repository. Anybody may create an RFC. The format should follow the templates in the RFC repository.
An RFC's number is the number of it's original proposal PR.
From "Proposed" an RFC may move to Exploring, or Closed stages. To move to Closed an FCP is required as in the existing process. A "Proposed" RFC may be moved to "Exploring" by consensus of the relevant team(s) without an FCP. See Exploring.
An Exploring RFC is one the Ember team believes should be pursued, but the RFC may still need some more work, discussion, answers to open questions, and/or a champion before it can move to the next stage.
An RFC is moved into Exploring with consensus of the relevant teams. The
relevant team expects to spend time helping to refine the proposal. The
RFC remains a PR and will have an Exploring label applied.
An Exploring RFC that is successfully completed can move to Accepted with an FCP is required as in the existing process. It may also be moved to Closed with an FCP.
An RFC that has been "accepted" has complete prose and has successfully passed through an "FCP to Accept" period in which the community has weighed in and consensus has been achieved on the direction. The relevant teams believe that the proposal is well-specified and ready for implementation. The RFC has a champion within one of the relevant teams.
If there are unanswered questions, we have outlined them and expect that they will be answered before Ready for Release.
When an RFC is merged and moved to "Accepted", a new PR will be opened to move it to Ready for Release. This PR should be used to track the implementation progress and gain consensus to move to the next stage.
The implementation is complete according to plan outlined in the RFC, and is in harmony with any changes in Ember that have occurred since the RFC was first written. This includes any necessary learning materials. At this stage, features or deprecations may be available for use behind a feature flag, or with an optional package, etc. The team reviews the work to determine when it can be included in a stable release. For codebase changes, there are no open questions that are anticipated to require breaking changes; the Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature. Today, this would be the "go/no-go" decision by a particular team.
This stage should include a list of criteria for determining when the proposal can be considered Recommended after being Released.
A PR is opened on the repo (see Accepted) to move an accepted RFC into this stage. An FCP is required to move into this stage.
Each Ember core team will be requested as a reviewer on the PR to move into this stage. A representative of each team adds a review. If a team does not respond to the request, and after the conclusion of the FCP, it is assumed that the release may proceed.
The work is published. If it is codebase-related work, it is in a stable version of the relevant package(s). If there are any critical deviations from the original RFC, they are briefly noted at the top of the RFC.
If the work for an RFC is spread across multiple releases of Ember or other packages, the RFC is considered to be in the Released stage when all features are available in stable releases and those packages and versions are noted in the RFC frontmatter.
Ember's RFC process can be used for process and work plans that are not about code. Some examples include Roadmap RFCs, changes to the RFC process itself, and changes to learning resources. When such an RFC is a candidate for Released, the work should be shipped as described, and the result should presented to the team with the intent of gathering feedback about whether anything is missing. If there is agreement that the work is complete, the RFC may be marked "Released" and a date is provided instead of a version.
An RFC is moved into "Released" when the above is verified by consensus of the relevant team(s) via a PR to update the stage.
The "Recommended" stage is the final milestone for an RFC. It provides a signal to the wider community to indicate that a feature has been put through its ecosystem paces and is ready to use.
The "Recommended" stage is most important for suites of features that are designed as a number of separate RFCs. It allows the Ember maintainers to stabilize individual features once they are technically feature complete, an important goal for maintaining technical velocity.
To reach the "Recommended" stage, the following should be true:
An RFC is moved into "Recommended" via PR to update the stage. An FCP is required to enter this stage. Multiple RFCs may be moved as a batch into "Recommended" with the same PR.
A Proposed or Exploring RFC may be closed after an FCP period. This is the same as the existing process. A closed RFC is discontinued.
A previously Accepted RFC may be discontinued at any point. The RFC may be superseded, out-of-date, or no longer consistent with the direction of Ember.
Following the RFC repository is the best way to keep up with the proposed changes to Ember and with the implementation of accepted changes.
Watching the repository will alert you to any newly created RFCs. Setting up notifications on a particular pull request will help you follow the progress of that RFC.
RFCs in Final Comment Periods are labeled with
Final Comment Period
and are announced in #news-and-announcements on Ember Discord and
on the Ember twitter account.
Quick links are provided at the top of the README to help you review what you are interested in.
Comments are the very heart of the RFC process. Comments are the primary way community members and core team members can provide feedback and collaborate on the design of a feature.
Comments should also be used to ensure the author has completed the RFC template and addressed implications of the feature across the Ember project, including documentation, addons, and tooling.
Comments should be constructive and respectful, following our Community Guidelines.
You need to follow this process if you intend to make "substantial" changes to Ember, Ember Data, Ember CLI, their documentation, or any other projects under the purview of the Ember core teams. What constitutes a "substantial" change is evolving based on community norms, but may include the following:
Some changes do not require an RFC:
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. We also highly recommend sharing drafts of RFCs in #dev-rfc on
the Ember Discord for early feedback.
The process for a successful RFC involves several Stages that take the proposed change all the way from proposal to implemented and widely adopted. A newly opened RFC is in the first stage, appropriately named, Proposed.
0000-template.md,
for deprecation RFCs it is deprecation-template.md.
Copy the template file to text/0000-my-feature.md, where
'my-feature' is descriptive. Don't assign an RFC number yet.The RFC Process requires finding a champion from the relevant core teams. The champion is responsible for representing the RFC in team meetings, and for shepherding its progress. Read more about the Champion's job
Find one via Discord.
The dev-rfc channel on the Ember Discord is
reserved for the discussion of RFCs. We highly recommend circulating early drafts of
your RFC in this channel to both receive early feedback and to find a champion.
Ask for a champion via an issue, or in the RFC itself. We monitor the RFC repository. We will circulate requests for champions, but highly recommend discussing the RFC in Discord.
Coordination and tracking of implementation of an RFC is done primarily on the pull request to advance the RFC to the Ready for Release stage.
The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) is welcome to work on the implementation.
If you are interested in working on the implementation for an Accepted RFC, but cannot determine if someone else is already working on it, please ask (e.g. by leaving a comment on the pull request to advance the RFC to the Ready for Release stage).
A merged RFC may be edited via a Pull Request process. Edits may include things like:
<blog post> for more information
about this feature." This note is not intended to be updated across time.Major changes should have a new RFC. The old RFC is moved to the Discontinued stage when the replacement is merged.
The RFC template requires indicating the relevant core teams. The following table offers a reference of teams responsible for each project. Please reach out for further guidance.
| Core Team | Project/Topics | Github Team |
|---|---|---|
| Ember.js | Ember.js | @emberjs/Framework |
| Ember Data | Ember Data | @emberjs/ember-data-core |
| Ember CLI | Ember CLI | @emberjs/cli |
| Learning | Documentation, Website, learning experiences | @emberjs/learning-core |
| TypeScript | TypeScript integration and design | @emberjs/typescript-core |
| Steering | Governance | @emberjs/steering |
For certain stage advancements, a final comment period (FCP) is required. This
is a period lasting 7 days. The beginning of this period will be signaled with a
comment and tag on the RFC's pull request. Furthermore, a message will be posted in
#news-and-announcements on Ember Discord and on the
official Ember Twitter account to attract the community's attention.
An RFC can be modified based upon feedback from the core teams and community during the final comment period. Significant modifications may trigger a new final comment period.
At the end of a successful FCP, the RFC moves into the stage specified.
An RFC may be closed or discontinued by the core teams after public discussion has settled and comments have been made summarizing the rationale for closing. The RFC will enter a "final comment period to close" lasting 7 days. At the end of the "FCP to close" period, the PR will be closed.
An RFC author may withdraw their own RFC by closing it themselves.
Each core team is responsible for reviewing open RFCs. The team must ensure that if an RFC is relevant to their team's responsibilities the team is correctly specified in the 'Relevant Team(s)' section of the RFC front-matter. The team must also ensure that each RFC addresses any consequences, changes, or work required in the team's area of responsibility.
As it is with the wider community, the RFC process is the time for teams and team members to push back on, encourage, refine, or otherwise comment on proposals.
As described in Ready for Release, each core team is responsible for reviewing RFCs that are ready to move to that stage.
@emberjs about the FCPFor RFCs opened before the implementation of Staged RFCs did not get advancement PRs to their next stage. See the automations docs for instructions on how to trigger the advancement workflow.
Ember's RFC process owes its inspiration to the Rust RFC process