Repository files navigation

The RFC ("request for comments") process is how Ember designs andachieves consensus on "substantial" proposed changes.

Many changes, including bug fixes and documentation improvements can beimplemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be putthrough a bit of a design process and produce a consensus among the Embercore teams.

The process is intended to provide a consistent and controlled path for newfeatures and changes to enter the framework. RFCs can be created by any memberof the community.

• Proposed RFCs

• Exploring RFCs

• PRs to advance an RFC to Ready for Release Stage

• PRs to advance an RFC to Released Stage

• PRs to advance an RFC to Recommended Stage

• RFCs in Final Comment Period for any Stage

• RFCs in FCP to Close

RFC Website

This site shows the current state and text of all RFCs in Accepted or later stages.

• Introduction
• Quick links
• Table of Contents
• How it works
• Stages
  • Proposed
  • Exploring
  • Accepted
  • Ready for Release
  • Released
  • Recommended
• Following RFC Progress
• Commenting on an RFC
• Creating an RFC
  • When you need to follow this process
  • Gathering feedback before submitting an RFC
  • The Process
    • How to create a new RFC
    • Finding a champion
• Implementing an RFC
• Editing merged RFCs
• Reference
  • Relevant Teams
  • Final Comment Periods (FCP)
    • FCP to close
• For Core Team Members

New proposals for changes are submitted as pull requests to this repo using oneof the RFC templates, depending on what the RFC is proposing. The newly opened RFCis in theProposed stage. The RFC is then reviewed and commented upon bycore team members and the community. The core teams may move the RFC to theExploring stage via a label if they believe the RFC is worth exploring further.From there, with refinement, community consensus, and agreement by the relevantcore teams, the RFC enters aFinal Comment Period (FCP).If that period is successful, with no new unaddressed concerns raised, the RFCis merged and is now in theAccepted stage.

An RFC that does not achieve consensus to be accepted may enter aFinal Comment Period to move the RFC to theClosed stage.

Once the RFC is accepted, a draft pull request is automatically opened to advancethe RFC to theReady for Release stage. This pull request has a template that outlineswhat is necessary to merge the RFC into this stage. This pull request is where thecommunity can track the progress of the implementation of the RFC. Once the criteriato move toReady for Release are met, including commitment of the team to thefeature's stability, the PR to advance may be merged after aFinal 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 becomesReady for Release.

Once the RFC is merged asReady for Release, a pull request is automatically openedto advance the RFC to theReleased stage. This pull request has a template that outlineswhat is necessary to merge the RFC into this stage. The pull request is mergedwhen those requirements are met and the relevant team has consensus that the RFChas beenReleased. No FCP is required for this stage.

Once the RFC is merged asReleased, a pull request is automatically opened toadvance the RFC to theRecommended stage. This pull request has a template that outlineswhat is necessary to merge the RFC into this stage and can be used for communitycoordination. This advancement requires aFinal Comment Period to merge.

At this point, the RFC isRecommended and complete.

RFCs that have been merged to the repo can also move to theDiscontinued stage atany point via a pull request. This is done when the RFC is no longer relevant orthe feature is no longer supported.

Read more about the RFCStages.

Here are all the stages that an RFC can be in:

There are two additional statuses for RFCs that will not move forward:

• Discontinued - a previouslyAccepted RFC that is either in conflict with Ember's evolving programming model or is superseded by another active RFC.
• Closed - Proposed RFCs that will not be moved into the next stage.

Proposed RFCs are opened as pull requests to the RFC repository. Anybody maycreate 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 toExploring,orClosed stages.To move toClosed an FCP is required as in the existing process.A "Proposed" RFC may be moved to "Exploring" by consensus of the relevantteam(s) without an FCP. SeeExploring.

An Exploring RFC is one the Ember team believes should be pursued, but the RFCmay 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. Therelevant team expects to spend time helping to refine the proposal. TheRFC remains a PR and will have anExploring label applied.

An Exploring RFC that is successfully completed can move toAcceptedwith an FCP is required as in the existing process. It may also be moved toClosed with an FCP.

An RFC that has been "accepted" has complete prose and has successfully passedthrough an "FCP to Accept" period in which the community has weighed in andconsensus has been achieved on the direction. The relevant teams believe thatthe proposal is well-specified and ready for implementation. The RFC has achampion within one of the relevant teams.

If there are unanswered questions, we have outlined them and expect that theywill be answered beforeReady for Release.

When an RFC is merged and moved to "Accepted", a new PR will be opened to moveit toReady for Release. This PR should be used to trackthe implementation progress and gain consensus to move to the next stage.

The implementation is complete according to plan outlined in the RFC, and is inharmony with any changes in Ember that have occurred since the RFC was firstwritten. This includes any necessary learning materials. At this stage, featuresor deprecations may be available for use behind a feature flag, or with anoptional package, etc. The team reviews the work to determine when it can beincluded in a stable release. For codebase changes, there are no open questionsthat are anticipated to require breaking changes; the Ember team is ready tocommit to the stability of any interfaces exposed by the current implementationof the feature. Today, this would be the "go/no-go" decision by a particularteam.

This stage should include a list of criteria for determining when the proposalcan be consideredRecommended after beingReleased.

A PR is opened on the repo (seeAccepted) to move an accepted RFCinto 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 thisstage. A representative of each team adds a review. If a team does not respondto the request, and after the conclusion of the FCP, it is assumed that therelease may proceed.

The work is published. If it is codebase-related work, it is in a stable versionof the relevant package(s). If there are any critical deviations from theoriginal 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 instable 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, andchanges 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 feedbackabout 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 therelevant team(s) via a PR to update the stage.

The "Recommended" stage is the final milestone for an RFC. It provides a signalto the wider community to indicate that a feature has been put through itsecosystem paces and is ready to use.

The "Recommended" stage is most important for suites of features that are designedas a number of separate RFCs. It allows the Ember maintainers to stabilize individualfeatures once they are technically feature complete, an important goal for maintainingtechnical velocity.

To reach the "Recommended" stage, the following should be true:

• If appropriate, the feature is integrated into the tutorial and the guides prose.API documentation is polished and updates are carried through to other areas ofAPI docs that may not directly pertain to the feature.
• If the proposal replaces an existing feature, the addon ecosystem has largelyupdated to work with both old and new features.
• If the proposal updates or replaces an existing feature, high-quality codemods areavailable
• If needed, Ember debugging tools as well as popular IDE support have beenupdated to support the feature.
• If the feature is part of a suite of features that were designed to work togetherfor best ergonomics, the other features are also ready to be "Recommended".
• Any criteria for "Recommended" for this proposal that were established in theReady For Release stage have been met.

An RFC is moved into "Recommended" via PR to update the stage. An FCP is requiredto enter this stage. Multiple RFCs may be moved as a batch into "Recommended" withthe same PR.

AProposed orExploring RFC may be closed after an FCP period. This is the sameas the existing process. A closed RFC is discontinued.

A previouslyAccepted RFC may be discontinued at any point. The RFCmay be superseded, out-of-date, or no longer consistent with the direction ofEmber.

Following the RFC repository is the best way to keep up with the proposedchanges to Ember and with the implementation of accepted changes.

Watching the repository will alert you to any newly created RFCs. Setting upnotifications on a particular pull request will help you follow the progress ofthat RFC.

RFCs inFinal Comment Periods are labeled withFinal Comment Periodand are announced in#news-and-announcements onEmber Discord andon theEmber twitter account.

Quick linksare 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 communitymembers and core team members can provide feedback and collaborate on the designof a feature.

Comments should also be used to ensure the author has completed the RFC templateand addressed implications of the feature across the Ember project, includingdocumentation, addons, and tooling.

Comments should be constructive and respectful, following ourCommunity Guidelines.

You need to follow this process if you intend to make "substantial"changes to Ember, Ember Data, Ember CLI, their documentation, or any otherprojects under the purview of theEmber core teams.What constitutes a "substantial" change is evolving based on community norms,but may include the following:

• A new feature that creates new API surface area, and wouldrequire afeature flag if introduced.
• The removal of features that already shipped as part of the releasechannel.
• The introduction of new idiomatic usage or conventions, even if theydo not include code changes to Ember itself.

Some changes do not require an RFC:

• Rephrasing, reorganizing or refactoring
• Addition or removal of warnings
• Additions that strictly improve objective, numerical qualitycriteria (speedup, better browser support)
• Additions only likely to benoticed by other implementors-of-Ember,invisible to users-of-Ember.

If you submit a pull request to implement a new feature without goingthrough the RFC process, it may be closed with a polite request tosubmit an RFC first.

It's often helpful to get feedback on your concept before diving into thelevel of API design detail required for an RFC.You may open anissue on this repo to start a high-level discussion, with the goal ofeventually formulating an RFC pull request with the specific implementationdesign. We alsohighly recommend sharing drafts of RFCs in#dev-rfc ontheEmber Discord for early feedback.

The process for a successful RFC involves severalStages that takethe proposed change all the way from proposal to implemented and widely adopted.A newly opened RFC is in the first stage, appropriately named,Proposed.

• Fork the RFC repohttp://github.com/emberjs/rfcs
• Copy the appropriate template. For most RFCs, this is0000-template.md,for deprecation RFCs it isdeprecation-template.md.Copy the template file totext/0000-my-feature.md, where'my-feature' is descriptive. Don't assign an RFC number yet.
• Fill in the RFC. Put care into the details:RFCs that do notpresent convincing motivation, demonstrate understanding of theimpact of the design, or are disingenuous about the drawbacks oralternatives tend to be poorly-received.
• Fill in the relevant core teams. Use thetable below to map from projects toteams.
• Submit a pull request. As a pull request the RFC will receive designfeedback from the larger community, and the author should be preparedto revise it in response. The RFC is now in theProposed stage.
• Find a champion on the relevant core team. The champion is responsible forshepherding the RFC through the RFC process and representing it in core teammeetings.
• Update the pull request to add the number of the PR to the filename andadd a link to the PR in the header of the RFC.
• Build consensus and integrate feedback. RFCs that have broad supportare much more likely to make progress than those that don't receive anycomments.
• From here, the RFC moves to theExploring stage orClosed in the processexplained inStages.

The RFC Process requires finding a champion from the relevant core teams. Thechampion is responsible for representing the RFC in team meetings, and forshepherding its progress.Read more about the Champion's job

• Find one via Discord.Thedev-rfc channel on theEmber Discord isreserved for the discussion of RFCs. We highly recommend circulating early drafts ofyour 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 highlyrecommend discussing the RFC in Discord.

Coordination and tracking of implementation of an RFC is done primarily on thepull request to advance the RFC to theReady for Release stage.

The author of an RFC is not obligated to implement it. Of course, theRFC author (like any other developer) is welcome to work on the implementation.

If you are interested in working on the implementation for anAcceptedRFC, 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 totheReady for Release stage).

A merged RFC may be edited via a Pull Request process. Edits may include things like:

• Updating the stage
• An optional note at the top that summarizes minor adjustments to the RFCdesign, at the time that the RFC's work became available for general use. Thisnote can be very brief, and link out to other resources like a blog post. Forexample, an update might simply say "See<blog post> for more informationabout this feature." This note is not intended to be updated across time.
• Updating any part of the RFC prose, in order to keep a written record of thechanges and rationale.

Major changes should have a new RFC. The old RFC is moved to theDiscontinuedstage when the replacement is merged.

The RFC template requires indicating the relevant core teams. The following tableoffers a reference of teams responsible for each project. Please reach out forfurther guidance.

For certain stage advancements, afinal comment period (FCP) is required. Thisis a period lasting 7 days. The beginning of this period will be signaled with acomment and tag on the RFC's pull request. Furthermore, a message will be posted in#news-and-announcements onEmber Discord and on theofficial Ember Twitter account to attract the community's attention.

An RFC can be modified based upon feedback from thecore teams and communityduring the final comment period. Significant modifications may trigger a newfinal comment period.

At the end of a successful FCP, the RFC moves into the stage specified.

An RFC may be closed or discontinued by thecore teams after public discussionhas 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 endof 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 ensurethat if an RFC is relevant to their team's responsibilities the team iscorrectly specified in the 'Relevant Team(s)' section of the RFC front-matter.The team must also ensure that each RFC addresses any consequences, changes, orwork required in the team's area of responsibility.

As it is with the wider community, the RFC process is the time forteams and team members to push back on, encourage, refine, or otherwise commenton proposals.

As described inReady for Release, each core team is responsible forreviewing RFCs that are ready to move to that stage.

• When mentioning RFCs that have been merged, link to the merged version,not to the pull-request.

• Achieving consensus from the team(s) to move the RFC through the stages ofthe RFC process.
• Ensuring the RFC follows the RFC process.
• Shepherding the planning and implementation of the RFC. Before the RFC isAccepted, the champion may remove themselves. The champion may find a replacementchampion at any time.

• Assign the RFC to yourself

• Achieve consensus to move to the next stage from relevant core teams
• If the stage requires an FCP to enter, comment in the RFC to address anyoutstanding issues and to proclaim the start of the FCP period, and tweetfrom@emberjs about the FCP
• Ensure the RFC has had the filename and header updated with the PR number
• After the FCP period (if any), merge the RFC PR
• Ensure relevant teams plan out what is necessary to implement in the nextstage
• Prepare for advancing the RFC to the next stage if applicable (e.g.opening a placeholder PR)

For RFCs opened before the implementation ofStaged RFCsdid not get advancement PRs to their next stage. See theautomations docs for instructions on how to trigger the advancement workflow.

• Achieve consensus to move to "FCP to Close" from relevant core teams
• Comment in the RFC to explain the decision

• Comment about the end of the FCP period with no new info
• Close the PR

Ember's RFC process owes its inspiration to theRust RFC process