From 194b438ecd15d4edbf9afb315e60ce7071f76b1b Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Thu, 14 Dec 2017 08:40:56 +0000 Subject: [PATCH 1/3] Create 0300-rfc-process-update.md --- text/0300-rfc-process-update.md | 161 ++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 text/0300-rfc-process-update.md diff --git a/text/0300-rfc-process-update.md b/text/0300-rfc-process-update.md new file mode 100644 index 0000000000..2b5e49a6d2 --- /dev/null +++ b/text/0300-rfc-process-update.md @@ -0,0 +1,161 @@ +--- +tags: ember, ember-cli +--- + +- Start Date: 2018-02-04 +- RFC PR: https://github.com/emberjs/rfcs/pull/300 +- Ember Issue: (leave this empty) + +# RFC Process Update + +## Summary + +Introduce the idea of Core Champion to the Ember.js RFC process, merge Ember.js and Ember CLI RFCs repositories, +and add metadata to make cross-project RFCs easier. + +## Motivation + +The Ember community has been using the Request For Comments (RFC) process to great effect over the last few years. +The RFC process has proved invaluable. +Proposals by both Core and community members are discussed and refined, +with the result coming out much stronger. +Other projects like React also adopted an RFC process, lending external validation to this idea. + +Following its initial implementation, shortcomings of the RFC process as well as new requirements were identified, +which we will try to address in this proposal. + +### Confusion about emberjs/rfcs and ember-cli/rfcs + +The Ember project currently has two separate RFC processes for Ember.js and Ember CLI. + +This leads to confusion because community members must keep track of two different repositories in order to monitor progress. +The submitter must consider these differences during the lifecycle of the RFC. + +There are also some cases where it is not clear exactly where the RFC should be submitted. +This can also lead to multiple RFCs being written, one for each repository. +While multiple RFCs might be warranted in some cases, +it should be a choice instead of a limitation of the current processes. + +### Process does not cover sufficient areas of development + +RFCs to emberjs/rfcs and ember-cli/rfcs concern themselves mostly with features or deprecations to ember.js and ember-cli respectfully, with some ember-data proposals in emberjs/rfcs. + +Once again taking inspiration from Rust, they have experimented expanding the types of RFCs proposed +[crates.io default ranking](https://github.com/rust-lang/rfcs/blob/master/text/1824-crates.io-default-ranking.md) +[default URLs for documentation](https://github.com/rust-lang/rfcs/blob/master/text/1826-change-doc-default-urls.md). +The latter one, for example, would have been a useful RFC when designing the new [API docs](https://github.com/ember-learn/ember-api-docs). + +### Lingering RFCs + +The emberjs/rfcs repository currently has [54 issues](https://github.com/emberjs/rfcs/issues) and [62 PRs](https://github.com/emberjs/rfcs/pulls) open, and ember-cli/rfcs has [183 issues](https://github.com/ember-cli/ember-cli/issues) and [49 PRs](https://github.com/ember-cli/ember-cli/pulls). +A significant percentage of these have not been active in the recent past. + +We have kept PRs and issues open so people could more easily find the discussions, +but this has instead given a negative feeling of staleness, as RFCs linger open without new feedback. + +## Detailed design + +To address the issues raised in the “Motivation” section, I will propose changes to the current process. + +### Implement Core Champion + +To make sure that RFCs receive adequate support from the team, Ember CLI has implemented the idea of a champion associated with each RFC. +The goal is that in seeking a champion from the team, +the RFC author starts a dialogue with the team and gets some early feedback. +The champion is then responsible for representing the RFC in team meetings, and for shepherding its progress. + +This will be imported into emberjs/rfcs. + +### Improve the lifecycle of RFCs + +To address the triaging and inactivity problem of RFCs, I introduce the concept of FCP to close. + +Closing an RFC should be viewed as another triaging tool, not as a rejection of the RFC. +Sometimes a rewrite of an RFC would be so fundamental that it would benefit of a fresh discussion in a new thread. +Sometimes the original author is no longer active (Champions should help here as well), +and someone else might want to take over the work in a new RFC. +Sometimes the timing might not be right, or the feature might have been addressed some other way, and yes, +sometimes it might be something that is not aligned with the team's values for the project. + +A good example of this is the [Named Blocks RFC](https://github.com/emberjs/rfcs/blob/master/text/0226-named-blocks.md#motivation), +which lists in the motivation section previous attempts at similar ideas. + +Like the FCP to merge process, once an RFC is marked as FCP to close there will be a period of one week where people can raise new concerns. +After that period of one week, the respective team will review and close the RFC or extend the period for another week. + +### Merge ember-cli/rfcs into emberjs/rfcs + +Part of removing confusion about the process is having a central repository for all Ember RFCs. + +To achieve merging ember-cli/rfcs into emberjs/rfcs the following will be done: + +- Remove active/completed concepts from ember-cli/rfcs + - Add front matter + - Copy both active and completed RFC files into `text` of emberjs/rfcs +- Transfer active PRs and Issues to emberjs/rfcs +- Archive ember-cli/rfcs + +There are some concerns about links breaking when we move the files to emberjs/rfcs, +but given the fact that ember-cli/rfcs had the concept of active/completed by moving the files into different folders, +links were already being broken. + +The ember-cli/rfcs do not need name or numbering changes, as there is currently no duplicated name. +Going forward, the numbering should be unified by virtue of having a single repository. + +### Open process to more types of RFCs + +To build on the previous point, the front matter that is to be added to RFCs will make it easier to have RFCs for other areas of the project, +like the design of the web resources, Guides content, marketing content, or features for core addons. + +Given that Ember is [organized into teams](https://emberjs.com/team/), with each team being responsible for certain projects, +the RFC front matter should be oriented towards those teams. + +A list of the teams and respective projects should be added to the instructions, +possibly with the addition of per-team instructions on specifics of the project. +Additional templates might be created as well, such a design work template. + +### Provide more guidance for post-RFC + +At the moment it is not clear for some contributors what happens once an RFC is merged. +How and when should work to implement an RFC be done? + +## How We Teach This + +To ensure that contributors are updated on the RFC process and the process is clear, +the documentation should be improved in a couple of ways. + +The README should be updated to include information about Champions, +how they are assigned, what they do. +The README should include a description of the lifecycle of RFCs with the new "FCP to close" state, +and instructions on how to proceed with the implementation of the RFC once it is accepted. + +## Drawbacks + +### Adjustment period + +There are active RFCs in ember-cli/rfcs. Moving these discussions would be onerous, so they should be kept there until completion, and no new RFCs accepted. + +### Permalinks to ember-cli/rfcs proposals + +Moving the RFC files from ember-cli/rfcs (active or completed) to emberjs/rfcs can be seen as a breaking change, and could lead to someone linking to ember-cli/rfcs and then the RFC being updated in emberjs/rfcs. However, ember-cli/rfcs already suffers from a linking problem due to the active/completed folders, as RFCs need to be moved from one to the other even after being accepted. +This could be mitigated by introducing a warning in the RFC text directing people to the new source. + +## Alternatives + +None at the moment. + +## Unresolved questions + +### How do Champions get assigned to an RFC? + +More enterprising authors will likely reach out to team members on their own, +but the added burden of having to seek a Champion might discourage people from authoring RFCs. + +The various teams could agree to review new RFCs during the weekly calls and assign Champions? + +--- + +## Glossary + +- **RFC**: Request For Comments. The process by which a proposal is discussed by the community and then approved by an Ember team. +- **FCP**: Final Comment Period. Period of one week at the end of which an RFC is to be accepted or rejected by an Ember team. Extended in periods of one week if new concerns are raised. From 741064da406c6f3f9c8607e6c638381eba71f3ce Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Thu, 25 Oct 2018 17:14:32 +0100 Subject: [PATCH 2/3] fixup! Create 0300-rfc-process-update.md --- text/0300-rfc-process-update.md | 47 +++++++++++++++++---------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/text/0300-rfc-process-update.md b/text/0300-rfc-process-update.md index 2b5e49a6d2..2d23f522b6 100644 --- a/text/0300-rfc-process-update.md +++ b/text/0300-rfc-process-update.md @@ -21,41 +21,47 @@ Proposals by both Core and community members are discussed and refined, with the result coming out much stronger. Other projects like React also adopted an RFC process, lending external validation to this idea. -Following its initial implementation, shortcomings of the RFC process as well as new requirements were identified, -which we will try to address in this proposal. +During this time, the community and the core teams have identified shortcomings of the RFC process as well as new requirements, +which this proposal intends to address: ### Confusion about emberjs/rfcs and ember-cli/rfcs The Ember project currently has two separate RFC processes for Ember.js and Ember CLI. -This leads to confusion because community members must keep track of two different repositories in order to monitor progress. -The submitter must consider these differences during the lifecycle of the RFC. +This leads to confusion because the community needs to track of two different repositories for progress. +For contributors there is the overhead of having to decide where to file their RFC if the proposal involves both projects, +as well as being aware of the differences in the process during its lifecycle. -There are also some cases where it is not clear exactly where the RFC should be submitted. -This can also lead to multiple RFCs being written, one for each repository. -While multiple RFCs might be warranted in some cases, -it should be a choice instead of a limitation of the current processes. - -### Process does not cover sufficient areas of development +### The process does not cover sufficient areas of development RFCs to emberjs/rfcs and ember-cli/rfcs concern themselves mostly with features or deprecations to ember.js and ember-cli respectfully, with some ember-data proposals in emberjs/rfcs. -Once again taking inspiration from Rust, they have experimented expanding the types of RFCs proposed -[crates.io default ranking](https://github.com/rust-lang/rfcs/blob/master/text/1824-crates.io-default-ranking.md) -[default URLs for documentation](https://github.com/rust-lang/rfcs/blob/master/text/1826-change-doc-default-urls.md). -The latter one, for example, would have been a useful RFC when designing the new [API docs](https://github.com/ember-learn/ember-api-docs). +We do not have a process for some kinds of initiatives, like a website redesign, +information architecture suggestions, SEO suggestions, and the like. ### Lingering RFCs -The emberjs/rfcs repository currently has [54 issues](https://github.com/emberjs/rfcs/issues) and [62 PRs](https://github.com/emberjs/rfcs/pulls) open, and ember-cli/rfcs has [183 issues](https://github.com/ember-cli/ember-cli/issues) and [49 PRs](https://github.com/ember-cli/ember-cli/pulls). -A significant percentage of these have not been active in the recent past. +The emberjs/rfcs repository currently has [86 issues](https://github.com/emberjs/rfcs/issues) and [67 PRs](https://github.com/emberjs/rfcs/pulls) open, and ember-cli/rfcs has [21 issues](https://github.com/ember-cli/ember-cli/issues) and [34 PRs](https://github.com/ember-cli/ember-cli/pulls). +A percentage of these have not been active in the recent past. We have kept PRs and issues open so people could more easily find the discussions, but this has instead given a negative feeling of staleness, as RFCs linger open without new feedback. +### Gaps between RFC proposal, implementation work, and release + +At the moment the process underspecifies what happens when an RFC is accepted and merged. +Even with the presence of the statusboard, +it has been hard to communicate to the community the status of the various initiatives. + ## Detailed design -To address the issues raised in the “Motivation” section, I will propose changes to the current process. +To address the issues raised in the “Motivation” section, I propose the following changes: + +- Add frontmatter to RFC files denoting which teams are involved +- Unify emberjs/rfcs and ember-cli/rfcs +- Define how core champions are assigned +- Add the concept of FCP to close +- Define how to track the implementation after an RFC is accepted ### Implement Core Champion @@ -146,12 +152,7 @@ None at the moment. ## Unresolved questions -### How do Champions get assigned to an RFC? - -More enterprising authors will likely reach out to team members on their own, -but the added burden of having to seek a Champion might discourage people from authoring RFCs. - -The various teams could agree to review new RFCs during the weekly calls and assign Champions? +None at the moment. --- From ca7b6c5c1b10ae08cfbad31560b58f72921f34e1 Mon Sep 17 00:00:00 2001 From: Katie Gengler Date: Sat, 3 Nov 2018 19:03:19 -0400 Subject: [PATCH 3/3] Update RFC process update RFC --- text/0300-rfc-process-update.md | 116 +++++++++++++++----------------- 1 file changed, 56 insertions(+), 60 deletions(-) diff --git a/text/0300-rfc-process-update.md b/text/0300-rfc-process-update.md index 2d23f522b6..09b720434d 100644 --- a/text/0300-rfc-process-update.md +++ b/text/0300-rfc-process-update.md @@ -1,82 +1,88 @@ ---- -tags: ember, ember-cli ---- - - Start Date: 2018-02-04 - RFC PR: https://github.com/emberjs/rfcs/pull/300 - Ember Issue: (leave this empty) -# RFC Process Update +# RFC (Request for Comments) Process Update ## Summary -Introduce the idea of Core Champion to the Ember.js RFC process, merge Ember.js and Ember CLI RFCs repositories, -and add metadata to make cross-project RFCs easier. +Refine the Ember RFC process and have it apply to all Ember teams. ## Motivation -The Ember community has been using the Request For Comments (RFC) process to great effect over the last few years. -The RFC process has proved invaluable. -Proposals by both Core and community members are discussed and refined, +The Ember community has been using the RFC process to great effect over the last few years. +Proposals by both Core and community members are discussed and refined with the result coming out much stronger. -Other projects like React also adopted an RFC process, lending external validation to this idea. -During this time, the community and the core teams have identified shortcomings of the RFC process as well as new requirements, -which this proposal intends to address: +During this time, the community and the core teams have identified shortcomings +of the RFC process as well as new requirements, which this RFC intends to address: -### Confusion about emberjs/rfcs and ember-cli/rfcs +### Confusion between emberjs/rfcs and ember-cli/rfcs The Ember project currently has two separate RFC processes for Ember.js and Ember CLI. -This leads to confusion because the community needs to track of two different repositories for progress. +This leads to confusion because the community needs to keep track of two different repositories. For contributors there is the overhead of having to decide where to file their RFC if the proposal involves both projects, -as well as being aware of the differences in the process during its lifecycle. +as well as being aware of the differences in the processes. -### The process does not cover sufficient areas of development +### The process does not cover the entire project -RFCs to emberjs/rfcs and ember-cli/rfcs concern themselves mostly with features or deprecations to ember.js and ember-cli respectfully, with some ember-data proposals in emberjs/rfcs. +RFCs to emberjs/rfcs and ember-cli/rfcs have traditionally concerned themselves with features or deprecations to Ember.js and Ember CLI respectfully, with some Ember Data proposals in emberjs/rfcs. -We do not have a process for some kinds of initiatives, like a website redesign, +We have already begun to use emberjs/rfcs for other initiatives, such as the project-wide Ember.js 2018 Roadmap but have not codified or updated the process to make it clear that it should be used for efforts such as a website redesign, information architecture suggestions, SEO suggestions, and the like. ### Lingering RFCs -The emberjs/rfcs repository currently has [86 issues](https://github.com/emberjs/rfcs/issues) and [67 PRs](https://github.com/emberjs/rfcs/pulls) open, and ember-cli/rfcs has [21 issues](https://github.com/ember-cli/ember-cli/issues) and [34 PRs](https://github.com/ember-cli/ember-cli/pulls). +Both the emberjs/rfcs and the ember-cli/rfcs repositories have many open issues and pull-requests. A percentage of these have not been active in the recent past. We have kept PRs and issues open so people could more easily find the discussions, -but this has instead given a negative feeling of staleness, as RFCs linger open without new feedback. - -### Gaps between RFC proposal, implementation work, and release +but this has instead given a negative impression of staleness, as RFCs linger open without new feedback. -At the moment the process underspecifies what happens when an RFC is accepted and merged. -Even with the presence of the statusboard, -it has been hard to communicate to the community the status of the various initiatives. +### The process for an RFC after it has been accepted +At the moment the process does not specify what happens when an RFC is accepted and merged. This has led to many questions about the status of merged RFCs. + ## Detailed design -To address the issues raised in the “Motivation” section, I propose the following changes: +### One RFC Process for all of Ember -- Add frontmatter to RFC files denoting which teams are involved -- Unify emberjs/rfcs and ember-cli/rfcs -- Define how core champions are assigned -- Add the concept of FCP to close -- Define how to track the implementation after an RFC is accepted +Ember is [organized into teams](https://emberjs.com/team/), with each team being responsible for certain projects. +The RFC process will be a useful tool for all of those projects. +The header of the RFC template will be updated to include a spot to specify the relevant team(s). The header will have "Ember Issue:" removed. + +A list of the teams and respective projects will be added to the instructions, +possibly with the addition of per-team instructions on specifics of the project. +Additional templates might be created as well, such a design work template. -### Implement Core Champion +Each team will be responsible for reviewing new RFCs and, if an RFC requires work from their team, ensuring that the RFC reflects that. +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. + +### Require a Core Champion To make sure that RFCs receive adequate support from the team, Ember CLI has implemented the idea of a champion associated with each RFC. -The goal is that in seeking a champion from the team, +One goal is that in seeking a champion from the team, the RFC author starts a dialogue with the team and gets some early feedback. -The champion is then responsible for representing the RFC in team meetings, and for shepherding its progress. +That champion is then responsible for representing the RFC in team meetings, and for shepherding its progress. We will import a version of this process to emberjs/rfcs: + +Each RFC will require a champion from the primary core team to which the RFC has been marked relevant. +The champion must be found by the opener of the RFC or other community member. They are not assigned by the core teams. +The champion will assign themselves on the RFC on Github. +The champion will be responsible for: + - achieving consensus from the team(s) to move the RFC through the stages of the RFC process. + - ensuring the RFC follows the RFC process. + - shepherding the planning and implementation of the RFC. +Before the RFC is accepted, the champion may remove themselves. +The champion may find a replacement champion at any time. -This will be imported into emberjs/rfcs. +A section on 'Finding a champion' will be added to the instructions on proposing an RFC. -### Improve the lifecycle of RFCs +### Introduce the concept of "FCP to close" -To address the triaging and inactivity problem of RFCs, I introduce the concept of FCP to close. +To address the problem of RFC triage and inactivity, this RFC introduces the concept of FCP to close. -Closing an RFC should be viewed as another triaging tool, not as a rejection of the RFC. +Closing an RFC should be viewed as another triage tool, not as a rejection of the RFC. Sometimes a rewrite of an RFC would be so fundamental that it would benefit of a fresh discussion in a new thread. Sometimes the original author is no longer active (Champions should help here as well), and someone else might want to take over the work in a new RFC. @@ -91,13 +97,12 @@ After that period of one week, the respective team will review and close the RFC ### Merge ember-cli/rfcs into emberjs/rfcs -Part of removing confusion about the process is having a central repository for all Ember RFCs. +We will have a single repository for all Ember Project RFCs. To achieve merging ember-cli/rfcs into emberjs/rfcs the following will be done: -- Remove active/completed concepts from ember-cli/rfcs - - Add front matter - - Copy both active and completed RFC files into `text` of emberjs/rfcs +- Add to the RFC header to indicate it applies to ember-cli +- Copy both active and completed RFC files into `text` of emberjs/rfcs - Transfer active PRs and Issues to emberjs/rfcs - Archive ember-cli/rfcs @@ -108,32 +113,23 @@ links were already being broken. The ember-cli/rfcs do not need name or numbering changes, as there is currently no duplicated name. Going forward, the numbering should be unified by virtue of having a single repository. -### Open process to more types of RFCs - -To build on the previous point, the front matter that is to be added to RFCs will make it easier to have RFCs for other areas of the project, -like the design of the web resources, Guides content, marketing content, or features for core addons. +### Track RFCs after they are accepted -Given that Ember is [organized into teams](https://emberjs.com/team/), with each team being responsible for certain projects, -the RFC front matter should be oriented towards those teams. - -A list of the teams and respective projects should be added to the instructions, -possibly with the addition of per-team instructions on specifics of the project. -Additional templates might be created as well, such a design work template. +At the moment it is not clear what happens to an RFC after it has been merged. -### Provide more guidance for post-RFC +This RFC proposes that after an RFC is merged, the relevant teams, guided by the champion, +will plan implementation by creating tracking issues in the relevant projects. -At the moment it is not clear for some contributors what happens once an RFC is merged. -How and when should work to implement an RFC be done? +This RFC proposes having a single place to track the implementation of each RFC. +Each RFC will have a header `Tracking:` that will be filled out with a link. At that link all issues related to that RFC, across all projects and organizations, will be enumerated. ## How We Teach This To ensure that contributors are updated on the RFC process and the process is clear, the documentation should be improved in a couple of ways. -The README should be updated to include information about Champions, -how they are assigned, what they do. -The README should include a description of the lifecycle of RFCs with the new "FCP to close" state, -and instructions on how to proceed with the implementation of the RFC once it is accepted. +The README will be updated to reflect process changes described in this RFC. +We will add checklists to the instructions for each stage of the RFC process to make it very clear what needs to happen. ## Drawbacks