From 6817cf2e5be7a8017c0f1fb86347a6bf2ce7ee83 Mon Sep 17 00:00:00 2001 From: Peter Wagenet Date: Wed, 3 Aug 2022 12:04:32 -0700 Subject: [PATCH 1/5] Add missing frontmatter --- ...0001-transform-attribute-meta-parameter.md | 12 +- text/0003-block-params.md | 5 + text/0003-cli-ember-doctor.md | 5 + text/0010-engines.md | 4 + text/0011-improved-cp-syntax.md | 4 + text/0012-help-json-output.md | 3 + text/0015-the-road-to-ember-2-0.md | 7 +- text/0020-sri-default.md | 3 + text/0023-command-line-completion.md | 1 + text/0024-bound-attributes.md | 6 +- text/0028-app-import-output-file.md | 4 + ...0029-addon-black-and-whitelist-for-apps.md | 4 + text/0045-internet-explorer.md | 5 + text/0046-cli-improved-release-process.md | 9 +- text/0046-registry-reform.md | 4 + text/0050-cli-production-code-stripping.md | 3 + text/0050-improved-actions.md | 4 + text/0053-helpers.md | 4 + text/0055-anonymous-amd.md | 4 + text/0056-improved-release-cycle.md | 30 ++-- text/0057-ember-data-reference-unification.md | 5 + text/0058-helper-listing.md | 4 + text/0061-ember-data-background-fetch.md | 25 +-- text/0064-contextual-component-lookup.md | 4 + text/0065-deprecation-warning-handlers.md | 4 + text/0080-serve-file-api.md | 4 + text/0086-firefox-in-ci.md | 3 + text/0090-addon-tree-caching.md | 4 + ...ddon-instrumentation-experimental-hooks.md | 4 + text/0091-weakmap.md | 6 +- text/0092-blueprint-remove-old-files.md | 4 + text/0095-cli-standardise-targets.md | 3 + text/0095-router-service.md | 14 +- text/0096-enable-yarn-usage.md | 3 + text/0101-ember-data-friendly-errors.md | 5 + text/0105-addons-optionalDependencies.md | 4 + text/0108-add-custom-transform.md | 4 + text/0110-packaging.md | 4 + text/0114-add-template-lint-addon.md | 4 + text/0116-qunit-dom.md | 7 +- text/0120-cli-guides.md | 19 +- text/0120-route-serializers.md | 5 + text/0121-remove-ember-cli-eslint.md | 3 + text/0136-contains-to-includes.md | 4 + text/0139-isHtmlSafe.md | 4 + text/0143-module-unification.md | 4 + text/0150-factory-for.md | 4 + text/0176-javascript-module-api.md | 4 + text/0178-deprecate-ember-k.md | 4 + .../0181-deprecate-ember-data-initializers.md | 4 + ...186-track-unique-history-location-state.md | 6 +- ...deprecate-component-lifecycle-hook-args.md | 4 + text/0194-deprecate-custom-event-manager.md | 4 + text/0213-custom-components.md | 5 + text/0225-ember-engines-mount-params.md | 5 + text/0226-named-blocks.md | 3 + ...9-deprecate-testing-restricted-resolver.md | 35 ++-- text/0232-simplify-qunit-testing-api.md | 68 +++---- text/0236-deprecation-ember-string.md | 3 + text/0237-deprecation-ember-map.md | 4 + text/0240-es-classes.md | 4 + text/0252-browser-support-changes.md | 8 +- text/0268-acceptance-testing-refactor.md | 8 +- ...on-native-function-prototype-extensions.md | 3 + text/0276-named-args.md | 4 + text/0278-template-only-components.md | 8 +- text/0280-remove-application-wrapper.md | 4 + text/0281-es5-getters.md | 4 + text/0286-block-let-template-helper.md | 4 + text/0287-promote-in-element-to-public-api.md | 3 + text/0293-record-data.md | 52 +++--- text/0294-optional-jquery.md | 148 ++++++++-------- text/0297-deprecate-ember-logger.md | 80 +++++---- text/0300-rfc-process-update.md | 37 ++-- ...0308-deprecate-property-lookup-fallback.md | 4 + text/0311-angle-bracket-invocation.md | 4 + text/0318-array-helper.md | 3 + text/0322-deprecate-copy-copyable.md | 6 +- text/0324-deprecate-component-isvisible.md | 11 +- text/0326-ember-data-filter-deprecation.md | 7 +- ...-deprecated-ember-evented-in-ember-data.md | 3 + text/0331-deprecate-globals-resolver.md | 3 + text/0332-ember-data-record-links-and-meta.md | 10 +- text/0334-deprecate-ember-utils.md | 11 -- text/0335-deprecate-send-action.md | 6 +- text/0337-native-class-constructor-update.md | 4 + text/0340-deprecate-ember-merge.md | 10 +- text/0345-discord.md | 24 +-- text/0364-roadmap-2018.md | 8 +- .../0369-deprecate-computed-clobberability.md | 3 + text/0370-deprecate-computed-volatile.md | 3 + text/0372-ember-data-model-factory-for.md | 20 ++- text/0373-Element-Modifier-Managers.md | 5 + ...75-deprecate-computed-property-modifier.md | 3 + text/0386-remove-jquery.md | 71 ++++---- text/0389-dynamic-tag-names.md | 3 + text/0391-router-helpers.md | 4 + ...precate-component-manager-string-lookup.md | 5 + text/0395-ember-data-packages.md | 3 + text/0398-RouteInfo-Metadata.md | 4 + text/0403-ember-data-identifiers.md | 108 +++++------ text/0408-decorators.md | 3 + text/0410-tracked-properties.md | 3 + text/0415-render-element-modifiers.md | 3 + text/0416-glimmer-components.md | 3 + text/0418-deprecate-route-render-methods.md | 3 + ...-deprecate-application-controller-props.md | 5 +- text/0425-website-redesign.md | 3 + text/0431-guides-restructure.md | 7 +- text/0432-contextual-helpers.md | 4 + text/0435-modifier-splattributes.md | 3 + text/0440-decorator-support.md | 3 + text/0445-deprecate-with.md | 3 + text/0446-contribution-guides.md | 3 + text/0449-deprecate-partials.md | 5 +- .../0451-injection-parameter-normalization.md | 3 + text/0452-ember-data-medium-term-plan.md | 14 +- text/0457-nested-lookups.md | 3 + .../0459-angle-bracket-built-in-components.md | 3 + text/0460-yieldable-named-blocks.md | 3 + text/0461-ember-data-singleton-record-data.md | 5 + text/0463-record-data-state.md | 18 +- text/0465-record-data-errors.md | 12 +- text/0466-request-state-service.md | 8 +- text/0468-classic-decorator.md | 3 + text/0470-fn-helper.md | 3 + text/0471-on-modifier.md | 3 + text/0477-blueprints-update.md | 4 + text/0478-tracked-properties-updates.md | 3 + text/0481-component-templates-co-location.md | 3 + text/0486-deprecate-mouseenter.md | 45 ++--- text/0487-custom-model-classes.md | 60 ++++--- text/0491-deprecate-disconnect-outlet.md | 3 + text/0494-async-observers.md | 4 + text/0496-handlebars-strict-mode.md | 3 + text/0507-embroider-v2-package-format.md | 4 + text/0519-2019-2020-roadmap.md | 4 + text/0521-find-by-identifier.md | 4 + text/0522-default-serializers-and-adapters.md | 4 + ...0523-model-argument-for-route-templates.md | 3 + text/0554-deprecate-getwithdefault.md | 8 +- text/0558-edition-detection.md | 3 + text/0560-add-equality-operators.md | 14 +- text/0562-add-logical-operators.md | 4 +- text/0566-memo-decorator.md | 1 + text/0580-destroyables.md | 4 + text/0581-new-test-waiters.md | 5 + text/0585-improved-ember-registry-apis.md | 37 ++-- text/0615-autotracking-memoization.md | 4 + text/0617-rfc-stages.md | 167 +++++++++--------- text/0625-helper-managers.md | 4 + text/0626-invoke-helper.md | 4 + text/0628-prettier.md | 3 + .../0631-refresh-method-for-router-service.md | 6 +- text/0635-ember-new-lang.md | 18 +- text/0637-customizable-test-setups.md | 74 ++++---- text/0638-interactive-app-creation.md | 56 +++--- text/0639-replace-blacklist-whitelist.md | 4 + text/0645-add-ember-page-title-addon.md | 3 + text/0649-deprecation-staging.md | 4 + text/0659-unique-id-helper.md | 20 ++- text/0669-tracked-storage-primitive.md | 1 + text/0671-modernize-built-in-components-1.md | 3 + text/0673-deprecate-tryinvoke.md | 3 + ...nsition-methods-of-controller-and-route.md | 9 +- text/0680-implicit-injection-deprecation.md | 4 +- text/0685-new-browser-support-policy.md | 1 + ...ecate-old-manager-capabilities-versions.md | 1 + text/0689-deprecate-has-block.md | 4 +- text/0690-deprecate-attrs-in-templates.md | 4 +- ...e-class-binding-and-class-name-bindings.md | 4 +- text/0692-deprecate-array-observers.md | 4 +- ...-deprecate-link-to-positional-arguments.md | 4 +- text/0702-eslint-plugin-qunit.md | 4 +- ...0704-deprecate-octane-optional-features.md | 4 +- .../0705-deprecate-jquery-optional-feature.md | 4 +- text/0706-deprecate-ember-global.md | 4 +- text/0707-modernize-built-in-components-2.md | 4 +- text/0711-deprecate-auto-location.md | 1 + .../0738-ember-data-deprecate-model-reopen.md | 1 + ...data-deprecate-non-strict-relationships.md | 13 +- ...data-deprecate-non-strict-relationships.md | 7 +- ...odel-static-field-access-without-lookup.md | 13 +- text/0748-glimmer-component-signature.md | 1 + text/0750-deprecate-ember-assign.md | 4 +- text/0752-inject-service.md | 12 +- text/0756-helper-default-manager.md | 1 + text/0772-deprecate-bower-support.md | 1 + text/0785-remove-set-get-in-tests.md | 1 + text/0786-ember-cookbook.md | 25 +-- ...ymporphic-relations-without-inheritance.md | 13 +- ...data-schema-definition-service-simplify.md | 13 +- text/0795-ember-data-return-promise-save.md | 5 +- ...e-blacklist-and-whitelist-build-options.md | 1 + 194 files changed, 1320 insertions(+), 711 deletions(-) diff --git a/text/0001-transform-attribute-meta-parameter.md b/text/0001-transform-attribute-meta-parameter.md index 2716cb23db..bd884d317a 100644 --- a/text/0001-transform-attribute-meta-parameter.md +++ b/text/0001-transform-attribute-meta-parameter.md @@ -1,14 +1,18 @@ --- +Stage: Released Start Date: 2014-08-14 +Release Date: 2016-05-03 +Release Versions: + ember-data: v2.5.0 +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/1 Ember Issue: https://github.com/emberjs/data/pull/4086 - --- # Summary For Ember Data. Pass through attribute meta data, which includes `parentType`, `options`, `name`, etc., -to the transform associated with that attribute. This will allow provide the following function signiture updates to `DS.Transform`: +to the transform associated with that attribute. This will allow provide the following function signiture updates to `DS.Transform`: * `transform.serialize(deserialized, attributeMeta)` * `transform.deserialize(serialized, attributeMeta)` @@ -66,10 +70,10 @@ App.MarkdownTransform = DS.Transform.extend({ serialize: function (deserialized, attributeMeta) { return deserialized.raw; }, - + deserialize: function (serialized, attributeMeta) { var options = attributeMeta.options.markdown || {}; - + return marked(serialized, options); } }); diff --git a/text/0003-block-params.md b/text/0003-block-params.md index ae56db494f..eb71131273 100644 --- a/text/0003-block-params.md +++ b/text/0003-block-params.md @@ -1,5 +1,10 @@ --- +Stage: Recommended Start Date: 2014-08-18 +Release Date: 2015-02-07 +Release Versions: + ember-source: v1.10.0 +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/3 Issues: Ember Stream support: emberjs/ember.js#5522 diff --git a/text/0003-cli-ember-doctor.md b/text/0003-cli-ember-doctor.md index b3fa246b17..474f93aded 100644 --- a/text/0003-cli-ember-doctor.md +++ b/text/0003-cli-ember-doctor.md @@ -1,5 +1,10 @@ --- +Stage: Accepted Start Date: 2015-01-10 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/3 diff --git a/text/0010-engines.md b/text/0010-engines.md index a75d3b6c6c..c42daf63d6 100644 --- a/text/0010-engines.md +++ b/text/0010-engines.md @@ -1,5 +1,9 @@ --- +Stage: Released Start Date: 2014-10-24 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/10 Ember Issue: https://github.com/emberjs/ember.js/pull/12685 diff --git a/text/0011-improved-cp-syntax.md b/text/0011-improved-cp-syntax.md index a50d6f2458..613545c0f2 100644 --- a/text/0011-improved-cp-syntax.md +++ b/text/0011-improved-cp-syntax.md @@ -1,5 +1,9 @@ --- +Stage: Discontinued Start Date: 2014-09-30 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/11 Ember Issue: https://github.com/emberjs/ember.js/pull/9527 diff --git a/text/0012-help-json-output.md b/text/0012-help-json-output.md index 942d35937a..bb5e6a3d09 100644 --- a/text/0012-help-json-output.md +++ b/text/0012-help-json-output.md @@ -1,5 +1,8 @@ --- +Stage: Released Start Date: 2015-05-16 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/12 diff --git a/text/0015-the-road-to-ember-2-0.md b/text/0015-the-road-to-ember-2-0.md index f9d45ff256..63583512c2 100644 --- a/text/0015-the-road-to-ember-2-0.md +++ b/text/0015-the-road-to-ember-2-0.md @@ -1,5 +1,10 @@ --- +# FIXME: Is this correct? +Stage: Discontinued Start Date: 2014-12-03 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/15 Ember Issue: This RFC is implemented over many Ember PRs @@ -590,7 +595,7 @@ In order to do that refactoring, several things will change: * In addition to the asynchronous `model` hook in routes, routes will also be able to define a `attrs` hook, which can return additional asynchronous data that should be provided to the component. -* Routeable Components should be placed in a "pod" naming convention. For +* Routeable Components should be placed in a "pod" naming convention. For example, the component for the `blog-post` route would be `app/blog-post/component.js`. diff --git a/text/0020-sri-default.md b/text/0020-sri-default.md index 362156e3a8..792b39f960 100644 --- a/text/0020-sri-default.md +++ b/text/0020-sri-default.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2015-07-10 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/20 diff --git a/text/0023-command-line-completion.md b/text/0023-command-line-completion.md index f51079724b..0eb88abd14 100644 --- a/text/0023-command-line-completion.md +++ b/text/0023-command-line-completion.md @@ -1,4 +1,5 @@ --- +Stage: Accepted Start Date: 2015-08-18 Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/23 diff --git a/text/0024-bound-attributes.md b/text/0024-bound-attributes.md index 77d08d475a..c901a6b9d4 100644 --- a/text/0024-bound-attributes.md +++ b/text/0024-bound-attributes.md @@ -1,5 +1,9 @@ --- -Start Date: 2014-11-26 +Stage: Recommended +Start Date: 2014-11-26 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/24 --- diff --git a/text/0028-app-import-output-file.md b/text/0028-app-import-output-file.md index 9a25ac91a8..29c0d4c03e 100644 --- a/text/0028-app-import-output-file.md +++ b/text/0028-app-import-output-file.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2015-11-02 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/28 diff --git a/text/0029-addon-black-and-whitelist-for-apps.md b/text/0029-addon-black-and-whitelist-for-apps.md index c58c637e56..cc20d0523c 100644 --- a/text/0029-addon-black-and-whitelist-for-apps.md +++ b/text/0029-addon-black-and-whitelist-for-apps.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2015-11-11 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/29 diff --git a/text/0045-internet-explorer.md b/text/0045-internet-explorer.md index 271d64e32c..0bfbada0a6 100644 --- a/text/0045-internet-explorer.md +++ b/text/0045-internet-explorer.md @@ -1,5 +1,10 @@ --- +# FIXME: Is this correct? +Stage: Discontinued Start Date: 2015-06-07 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/45 --- diff --git a/text/0046-cli-improved-release-process.md b/text/0046-cli-improved-release-process.md index 56453e2ae1..63462e6dfc 100644 --- a/text/0046-cli-improved-release-process.md +++ b/text/0046-cli-improved-release-process.md @@ -1,12 +1,15 @@ --- +Stage: Recommended Start Date: 2016-03-26 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/46 --- # Improved Release Process - + ## Summary & Motivation ember-cli has followed an ad hoc release process throughout its existence which has made it difficult to know exactly when releases would come out, what features would and would not be supported, and the degree to which it would support existing Ember applications. With the proposal for lockstep SemVer there were ideals of guaranteeing compatibility, which we have mostly met, but that resulted in making decisions of delaying an official 2.X release of ember-cli to avoid additional major version bumps. @@ -20,7 +23,7 @@ To begin there will be three separate channels: canary, beta, and release. We in - **Canary**: represents the latest work in ember-cli, and is synonymous with the `HEAD` of the `master` branch and is the least stable of all channels. - **Beta**: branched off of master every six weeks, exact commit decided upon manually. Updated and released weekly with commits that are prefixed `[BUGFIX beta]`. Less stable than `release` as it is a proving ground. No new features will be added once the branch has been created to allow for existing features to mature. Tags will match Ember's patterns, for example `v2.6.0-beta.1`. Branch name: `beta`. - **Release**: branched off of Beta every six weeks. Only rarely will this be updated, but possible for security issues and uncaught regressions. Branch name: `release`. - + ember-cli will not support daily releases as time-based packaging doesn't make a lot of sense. ## New Features @@ -49,7 +52,7 @@ In order to undertake this task, there are multiple workflows which must occur: - [ ] Teaching new patterns to ember-cli contributors, most specifically commit tagging and feature flagging. - [ ] Increased automation of the release process. - [ ] Tooling to support feature flags. - + ## References - [Ember's Post-1.0 Release Cycle](http://emberjs.com/blog/2013/09/06/new-ember-release-process.html) diff --git a/text/0046-registry-reform.md b/text/0046-registry-reform.md index 0e5a2ddef6..321827dc31 100644 --- a/text/0046-registry-reform.md +++ b/text/0046-registry-reform.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-04-09 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/46 Ember Issue: https://github.com/emberjs/ember.js/pull/11440 diff --git a/text/0050-cli-production-code-stripping.md b/text/0050-cli-production-code-stripping.md index d2f6c50bb2..1388272810 100644 --- a/text/0050-cli-production-code-stripping.md +++ b/text/0050-cli-production-code-stripping.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2016-04-06 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/50 diff --git a/text/0050-improved-actions.md b/text/0050-improved-actions.md index f6722f9803..198ab49b81 100644 --- a/text/0050-improved-actions.md +++ b/text/0050-improved-actions.md @@ -1,5 +1,9 @@ --- +Stage: Discontinued Start Date: 2014-05-06 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/50 --- diff --git a/text/0053-helpers.md b/text/0053-helpers.md index 9feb3a9cbb..072b688693 100644 --- a/text/0053-helpers.md +++ b/text/0053-helpers.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-05-17 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/53 Ember Issue: https://github.com/emberjs/ember.js/pull/11278 diff --git a/text/0055-anonymous-amd.md b/text/0055-anonymous-amd.md index 193613fe53..535c3f2889 100644 --- a/text/0055-anonymous-amd.md +++ b/text/0055-anonymous-amd.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2016-06-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/55 diff --git a/text/0056-improved-release-cycle.md b/text/0056-improved-release-cycle.md index 37b5c7c671..5239db8ae9 100644 --- a/text/0056-improved-release-cycle.md +++ b/text/0056-improved-release-cycle.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-10-02 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/56 --- @@ -8,8 +12,8 @@ RFC PR: https://github.com/emberjs/rfcs/pull/56 Ember balances a desire for overall stability with a desire for continued improvements using a two-pronged approach: -* General adherence to Semantic Versioning, which means that we don't - make breaking changes to public, documented APIs except when the +* General adherence to Semantic Versioning, which means that we don't + make breaking changes to public, documented APIs except when the major version changes. * A rapid release cycle that allows us to ship additive changes to the framework on a regular, digestible basis. @@ -43,13 +47,13 @@ Ember 2.0 is the first major release cycle where we have followed these refineme * New features are added predictably, and it's relatively easy to follow the list of new APIs that are under development, and where they are in the process. -* There is little pressure for contributors to land a feature +* There is little pressure for contributors to land a feature prematurely, because missing a release deadline isn't catastrophic–there will be another train six weeks hence. * We have a lot of very good automation tools that keep the trains - running–commits can be (mostly) automatically backported to the + running–commits can be (mostly) automatically backported to the current beta or release version. -* Upgrading Ember itself from version to version is typically a quick +* Upgrading Ember itself from version to version is typically a quick process, except when private APIs are in use. We aim for upgrades to be possible to slot into existing product sprints, and the nature of the process means that we tend to hit this goal for most users. @@ -64,10 +68,10 @@ The process of getting from *here* to *there* is a series of incremental release While the approach we're using has provided a lot of benefits, there are a number of areas that could still use improvement: -* While it is in theory possible to upgrade only once every few +* While it is in theory possible to upgrade only once every few releases, there is no guidance about exactly how to do that, and little clarity about how many releases we plan to support with - security fixes. (Because of the two-step deprecations of heavily + security fixes. (Because of the two-step deprecations of heavily used private APIs, it is in practice important to go through each intermediate release to clear deprecation warnings before proceeding.) @@ -83,7 +87,7 @@ While the approach we're using has provided a lot of benefits, there are a numbe churn in the experience of using Ember without actual breakages. * While deprecations technically don't force you to change anything, in practice clearing deprecations is a part of the upgrade process. - A constant stream of deprecations, like in the lead-up to Ember 2.0, + A constant stream of deprecations, like in the lead-up to Ember 2.0, can feel almost as bad as breaking changes. * In the lead-up to Ember 2.0, a desire to remove as much cruft as quickly as possible led to a need to land new features with much @@ -121,15 +125,15 @@ In theory, it's possible to upgrade every few releases, instead of every release This means: -* We will only remove heavily used private APIs if they were +* We will only remove heavily used private APIs if they were deprecated in a previous LTS release. This means that - if a feature is deprecated in 2.3, the first LTS release that - the deprecation will appear in is 2.4, and it can therefore be + if a feature is deprecated in 2.3, the first LTS release that + the deprecation will appear in is 2.4, and it can therefore be removed in 2.5. * We will provide release notes for each LTS release that roll up the changes for the releases it includes, including new deprecations and new features. -* We will use the LTS releases to provide better big-picture +* We will use the LTS releases to provide better big-picture messaging on the goals of any deprecations and changes to idiomatic Ember. * Security fixes will always be backported to the most recent @@ -137,7 +141,7 @@ This means: * We will encourage the Ember ecosystem to maintain support for the LTS releases, and lead by example with our own projects that have not yet reached SemVer stability. Ideally, this - will give more of a voice to people who are upgrading less + will give more of a voice to people who are upgrading less frequently. This means that people who want to stay on the latest and greatest can continue to upgrade every six weeks (with the same SemVer guarantees we've come to expect), and people who want to upgrade less frequently can do so. diff --git a/text/0057-ember-data-reference-unification.md b/text/0057-ember-data-reference-unification.md index 1549649acb..3b17375ca4 100644 --- a/text/0057-ember-data-reference-unification.md +++ b/text/0057-ember-data-reference-unification.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2015-05-20 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/57 Ember Issue: https://github.com/emberjs/data/pull/3303 diff --git a/text/0058-helper-listing.md b/text/0058-helper-listing.md index 1afa9d850a..c9bafe6dba 100644 --- a/text/0058-helper-listing.md +++ b/text/0058-helper-listing.md @@ -1,5 +1,9 @@ --- +Stage: Discontinued Start Date: 2015-05-24 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/58 Ember Issue: https://github.com/emberjs/ember.js/pull/11393 diff --git a/text/0061-ember-data-background-fetch.md b/text/0061-ember-data-background-fetch.md index 7c2f9b409e..2c06f19f07 100644 --- a/text/0061-ember-data-background-fetch.md +++ b/text/0061-ember-data-background-fetch.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2015-06-03 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/61 Ember Issue: This RFC is implemented over many Ember Data PRs @@ -152,7 +157,7 @@ displaying a loading spinner. `shouldRefetchRecord` is a new method on the adapter that will be called by the store to make initial decision whether to refetch the record form the adapter or return the cached record from the store. This could method could be used to implement caching logic (e.g. only refetch this record after the time specified in its cache expires token) or for improved offline support (e.g. always refetch unless there is no internet connection then use cached record). -This record would only be called if the record was already found in the store and is in the loaded state. +This record would only be called if the record was already found in the store and is in the loaded state. This method is only checked by `store.findById` and `store.findAll`. Methods with `fetch` in their name always refetch the record(s) from the adapter. @@ -162,7 +167,7 @@ This method is only checked by `store.findById` and `store.findAll`. Methods wit `shouldRefetchRecord` returns true if the adapter determines the record is stale and should be refetch. It should return false if the record is not stale or some other condition indicates that a fetch should - not happen at this time (e.g. loss of internet connection). + not happen at this time (e.g. loss of internet connection). This method is synchronous. @@ -176,7 +181,7 @@ This method is only checked by `store.findById` and `store.findAll`. Methods wit } ``` -The method `shouldBackgroundUpdate` would be used by the store to make the decision to re-fetch the record after it has already been returned to the user. This would allow realtime adapter to opt out of the background fetch if the adapter is already subscribing to changes on the record. +The method `shouldBackgroundUpdate` would be used by the store to make the decision to re-fetch the record after it has already been returned to the user. This would allow realtime adapter to opt out of the background fetch if the adapter is already subscribing to changes on the record. ```js { @@ -184,7 +189,7 @@ The method `shouldBackgroundUpdate` would be used by the store to make the decis `shouldBackgroundUpdate` returns true if the store should re fetch a record in the store after returning it to the user to ensure the record has the most up to date data. - + This method is synchronous. @method shouldBackgroundUpdate @@ -198,7 +203,7 @@ The method `shouldBackgroundUpdate` would be used by the store to make the decis ``` -In the next major version of Ember Data the recommend way of finding a record +In the next major version of Ember Data the recommend way of finding a record will be: ```js @@ -260,7 +265,7 @@ Models have an `isReloading` flag. This will be deprecated in favor of the new ` Why should we *not* do this? -After the record has been updated in the background Ember's Data binding will cause any views to automatically update with the latest changes. This can result an a surprising "popping" effect which is especially pronounced when the background fetch resolves quickly (The user sees an initial render with the stale data then a quick re-render with the fresh data). +After the record has been updated in the background Ember's Data binding will cause any views to automatically update with the latest changes. This can result an a surprising "popping" effect which is especially pronounced when the background fetch resolves quickly (The user sees an initial render with the stale data then a quick re-render with the fresh data). @@ -269,12 +274,12 @@ After the record has been updated in the background Ember's Data binding will ca What other designs have been considered? What is the impact of not doing this? -One alternate option could be for Ember Data to track an expires token on a model. This would allow Ember -Data to behave like a caching proxy when fetching. If the record is expired, fetch should block. +One alternate option could be for Ember Data to track an expires token on a model. This would allow Ember +Data to behave like a caching proxy when fetching. If the record is expired, fetch should block. If the record is not expired it would return a resolve the record right away however still issue a -second request. +second request. -When used with backends that do not return an expires token. Ember Data would assume that the +When used with backends that do not return an expires token. Ember Data would assume that the record is stale (this could be configured on the adapter). diff --git a/text/0064-contextual-component-lookup.md b/text/0064-contextual-component-lookup.md index 2965cc04f2..76e76156f4 100644 --- a/text/0064-contextual-component-lookup.md +++ b/text/0064-contextual-component-lookup.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-06-12 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/64 --- diff --git a/text/0065-deprecation-warning-handlers.md b/text/0065-deprecation-warning-handlers.md index 6539dae628..2229b24756 100644 --- a/text/0065-deprecation-warning-handlers.md +++ b/text/0065-deprecation-warning-handlers.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-06-30 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/65 --- diff --git a/text/0080-serve-file-api.md b/text/0080-serve-file-api.md index eadf979fd6..aa58b598ca 100644 --- a/text/0080-serve-file-api.md +++ b/text/0080-serve-file-api.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2016-11-21 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/80 diff --git a/text/0086-firefox-in-ci.md b/text/0086-firefox-in-ci.md index 74c14e2971..c16f168830 100644 --- a/text/0086-firefox-in-ci.md +++ b/text/0086-firefox-in-ci.md @@ -1,5 +1,8 @@ --- +Stage: Discontinued Start Date: 2016-12-04 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/86 diff --git a/text/0090-addon-tree-caching.md b/text/0090-addon-tree-caching.md index acb2a8151c..8b68231919 100644 --- a/text/0090-addon-tree-caching.md +++ b/text/0090-addon-tree-caching.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2016-12-11 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/90 diff --git a/text/0091-cli-addon-instrumentation-experimental-hooks.md b/text/0091-cli-addon-instrumentation-experimental-hooks.md index 766d1d0b7f..11d2e8dc46 100644 --- a/text/0091-cli-addon-instrumentation-experimental-hooks.md +++ b/text/0091-cli-addon-instrumentation-experimental-hooks.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2016-12-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/91 diff --git a/text/0091-weakmap.md b/text/0091-weakmap.md index 8cc2bba59f..3390d357c5 100644 --- a/text/0091-weakmap.md +++ b/text/0091-weakmap.md @@ -1,5 +1,9 @@ --- +Stage: Discontinued Start Date: 2015-09-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/91 Ember Issue: https://github.com/emberjs/ember.js/pull/12224 / https://github.com/emberjs/ember.js/pull/12990 / https://github.com/emberjs/ember.js/pull/13688 @@ -23,7 +27,7 @@ just choose a direction. *Note: Just like ES2015 WeakMap, only non null Objects can be used as keys* *Note: `Ember.WeakMap` can be used interchangibly with the ES2015 WeakMap. This will allow us to eventually cut over entirely to the Native WeakMap.* - + # Motivation It is a common pattern to want to store private state about a specific object. diff --git a/text/0092-blueprint-remove-old-files.md b/text/0092-blueprint-remove-old-files.md index f0d2bf4e2f..96f30f5121 100644 --- a/text/0092-blueprint-remove-old-files.md +++ b/text/0092-blueprint-remove-old-files.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2016-12-17 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/92 diff --git a/text/0095-cli-standardise-targets.md b/text/0095-cli-standardise-targets.md index beee76675e..6f7d0584bc 100644 --- a/text/0095-cli-standardise-targets.md +++ b/text/0095-cli-standardise-targets.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-01-03 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/95 diff --git a/text/0095-router-service.md b/text/0095-router-service.md index 2b25713aa4..a637cab365 100644 --- a/text/0095-router-service.md +++ b/text/0095-router-service.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2015-09-24 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/95 Ember Issue: https://github.com/emberjs/ember.js/pull/14805 @@ -10,7 +14,7 @@ Ember Issue: https://github.com/emberjs/ember.js/pull/14805 This RFC proposes: - creating a public `router` service that is a superset of today's `Ember.Router`. - + - codifying and expanding the supported public API for the `transition` object that is currently passed to `Route` hooks. - introducing the `get-route-info` template helper @@ -163,7 +167,7 @@ So we should deprecate willTransition and didTransition in favor of the followin ### New Events: routeWillChange & routeDidChange -The `routeWillChange` event fires whenever a new route is chosen as the desired target of a transition. This includes `transitionTo`, `replaceWith`, all redirection for any reason including error handling, and abort. Aborting implies changing the desired target back to where you already were. Once a transition has completed, `routeDidChange` fires. +The `routeWillChange` event fires whenever a new route is chosen as the desired target of a transition. This includes `transitionTo`, `replaceWith`, all redirection for any reason including error handling, and abort. Aborting implies changing the desired target back to where you already were. Once a transition has completed, `routeDidChange` fires. Both events receive a single `transition` argument as described in the "Transition Object" section below, which explains the meaning of `from` and `to` in more detail. @@ -314,7 +318,7 @@ We propose `readsRouteInfo` for defining a component that reads route info: let MyComponent = Ember.Component.extend({ didInsertElement() { // Accessing routInfo here is intended to be indistinguishable - // from a normal, explicitly-passed input argument. + // from a normal, explicitly-passed input argument. doSomethingWith(this.get('routeInfo')); } }); @@ -344,7 +348,7 @@ We propose the `#with-route-info` keyword for setting a new route info: {{#with-route-info someValue}} {{!- within this block AND ALL ITS DESCENDANTS until - otherwise overridden by another set-route-info statement, + otherwise overridden by another set-route-info statement, `get-route-info` returns someValue. -}} {{/with-route-info}} @@ -368,7 +372,7 @@ Ember.Helper.extend({ }); ``` -A more complete version that also matches models and queryParams can be written in the same way. +A more complete version that also matches models and queryParams can be written in the same way. 2. We can improve `link-to` so that it always finds implicit model arguments from the local context, rather than trying to locate them on the global router service. This will fix longstanding bugs like https://github.com/ember-animation/liquid-fire/issues/347 and it will make it easier to test components that contain `{{link-to}}`. This would also open the door to relative link-tos. diff --git a/text/0096-enable-yarn-usage.md b/text/0096-enable-yarn-usage.md index f877bfa925..2b755e460f 100644 --- a/text/0096-enable-yarn-usage.md +++ b/text/0096-enable-yarn-usage.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-02-02 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/96 diff --git a/text/0101-ember-data-friendly-errors.md b/text/0101-ember-data-friendly-errors.md index 4386316c70..853b7d87fa 100644 --- a/text/0101-ember-data-friendly-errors.md +++ b/text/0101-ember-data-friendly-errors.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2015-10-23 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/101 Ember Issue: https://github.com/emberjs/data/pull/3930 diff --git a/text/0105-addons-optionalDependencies.md b/text/0105-addons-optionalDependencies.md index befc3e4f9b..f6a96db964 100644 --- a/text/0105-addons-optionalDependencies.md +++ b/text/0105-addons-optionalDependencies.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-04-23 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/105 diff --git a/text/0108-add-custom-transform.md b/text/0108-add-custom-transform.md index 744093876f..6e97409fbb 100644 --- a/text/0108-add-custom-transform.md +++ b/text/0108-add-custom-transform.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-06-18 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/108 diff --git a/text/0110-packaging.md b/text/0110-packaging.md index 9accad8578..10dd562f18 100644 --- a/text/0110-packaging.md +++ b/text/0110-packaging.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-09-07 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/110 diff --git a/text/0114-add-template-lint-addon.md b/text/0114-add-template-lint-addon.md index 47d7c74f07..e5bf123615 100644 --- a/text/0114-add-template-lint-addon.md +++ b/text/0114-add-template-lint-addon.md @@ -1,5 +1,9 @@ --- +# FIXME: Is this correct? We don't quite do what is specified here +Stage: Discontinued Start Date: 2018-01-04 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/114 diff --git a/text/0116-qunit-dom.md b/text/0116-qunit-dom.md index a2fe84377b..8a2f0c9f27 100644 --- a/text/0116-qunit-dom.md +++ b/text/0116-qunit-dom.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-02-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/116 @@ -104,7 +107,7 @@ migrate their existing tests to `qunit-dom` a basic codemod exists at - `qunit-dom` is another abstraction layer on top of the raw QUnit assertions which adds to the existing learning curve. - + - Adding `qunit-dom` to the default blueprint could make it look even more like `ember-mocha` is only a second-class citizen. Since we add it to the default `package.json` file it is easy to opt-out though and can be replaced with @@ -119,7 +122,7 @@ migrate their existing tests to `qunit-dom` a basic codemod exists at as mentioned above they still result in more verbose code than using `qunit-dom`. Another advantage is that `qunit-dom` generates a useful assertion description by default, while `assert.equal()` will just show - something like "A does not match B". + something like "A does not match B". > What is the impact of not doing this? diff --git a/text/0120-cli-guides.md b/text/0120-cli-guides.md index e318145357..f81325ac44 100644 --- a/text/0120-cli-guides.md +++ b/text/0120-cli-guides.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-07-30 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/120 @@ -23,7 +26,7 @@ in order to improve maintainability and empower new contributors. The CLI docs are currently a Jekyll app. Similar migrations have been very successful. The rewrite and/or reorganization of content is driven by an audit of the existing -content's relevance and balance. While trying to plan a refactor in place, it became clear that a greenfield approach is more time efficient and will lead to a +content's relevance and balance. While trying to plan a refactor in place, it became clear that a greenfield approach is more time efficient and will lead to a better learning experience. A significant portion of the content from the current guides site can be ported over once a new structure is in place. ## Detailed design @@ -34,13 +37,13 @@ Middleman apps to Ember. ### Writing process -Writing new content and porting over existing information is a job that will require the help of many contributors! After this RFC is accepted, a call for contributors will be made. +Writing new content and porting over existing information is a job that will require the help of many contributors! After this RFC is accepted, a call for contributors will be made. Here are some strategies to help contributor work to be successful: - A quest issue will outline sections that need work so that people can volunteer - Collaboration will be encouraged so that no one person blocks writing on a particular topic - Contributing can take multiple forms. For example, developers with some CLI expertise who don't have time/interest for formal writing can share some brief notes or suggestions to help out the writers. Writers don't need to be experts. In some cases, it's better when someone isn't very familiar with the content because they can help identify gaps. -- Each unwritten section will have comments in the markdown indicating which topics to cover. In cases where content has been ported over, comments will indicate which sections to fact-check, clarify, or revise. +- Each unwritten section will have comments in the markdown indicating which topics to cover. In cases where content has been ported over, comments will indicate which sections to fact-check, clarify, or revise. - A strike team channel will be created on a chat - A writing styleguide will be provided for contributors - Following a verson one release, writing work will be organized via normal GitHub issues. @@ -52,7 +55,7 @@ The beta version of the CLI Guides content can be found at [ember-learn/cli-guid ### User Personas The content layout should follow the progression of an Ember developer's -learning experience. There are four main user personas for the +learning experience. There are four main user personas for the CLI documentation: 1. A new or "typical" Ember CLI user - someone whose primary work is @@ -70,8 +73,8 @@ addon work, or who are planning for broad extensibility Applying these User Personas to the CLI content, the following topics layout emerges. "Beginner" topics will include links to later "Advanced" topics, similar to how the Guides link to the API docs. -- Introduction - - how to install ember cli +- Introduction + - how to install ember cli - a very simple, short definition of what it is (the official way to create, build, and test an Ember app) - Why is the CLI needed - Guidance on learning path @@ -92,7 +95,7 @@ topics, similar to how the Guides link to the API docs. - more configurations - Writing Addons - Overview - - Tutorial: Creating a standalone addon and an in-repo addon, + - Tutorial: Creating a standalone addon and an in-repo addon, - Using the dummy app - Including assets - Configuration @@ -131,7 +134,7 @@ apps that have been successfully turned into Ember apps. Some examples of past c [Chris Manson](https://github.com/mansona?tab=overview&from=2018-06-01&to=2018-06-30) has a project in development that automates the creation of documentation apps, integrating the lessons learned from these past conversions. Early results are looking great! -The resulting app will make use of typography and UI assets from +The resulting app will make use of typography and UI assets from [ember-styleguide](https://github.com/ember-learn/ember-styleguide) Although only one version will be deployed/maintained for the forseeable future, the URL structure will allow for future growth, i.e. `https://cli.emberjs.com/release/some-topic` diff --git a/text/0120-route-serializers.md b/text/0120-route-serializers.md index facd359ad7..24c4e650c5 100644 --- a/text/0120-route-serializers.md +++ b/text/0120-route-serializers.md @@ -1,5 +1,10 @@ --- +# FIXME: Is this correct? Doesn't appear to be the recommended way of doing it. +Stage: Discontinued Start Date: 2016-02-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/120 Ember Issue: https://github.com/emberjs/ember.js/pull/13016 diff --git a/text/0121-remove-ember-cli-eslint.md b/text/0121-remove-ember-cli-eslint.md index d95956f55e..2473709700 100644 --- a/text/0121-remove-ember-cli-eslint.md +++ b/text/0121-remove-ember-cli-eslint.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-08-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/ember-cli/rfcs/pull/121 diff --git a/text/0136-contains-to-includes.md b/text/0136-contains-to-includes.md index 8df5f38c33..d5045fbdb4 100644 --- a/text/0136-contains-to-includes.md +++ b/text/0136-contains-to-includes.md @@ -1,5 +1,9 @@ --- +Stage: Discontinued Start Date: 2016-04-16 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/136 Ember Issue: https://github.com/emberjs/ember.js/pull/13553 diff --git a/text/0139-isHtmlSafe.md b/text/0139-isHtmlSafe.md index 5b511419a4..9418e42374 100644 --- a/text/0139-isHtmlSafe.md +++ b/text/0139-isHtmlSafe.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-04-18 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/139 Ember Issue: https://github.com/emberjs/ember.js/pull/13666 diff --git a/text/0143-module-unification.md b/text/0143-module-unification.md index 2c99bb8132..691c881385 100644 --- a/text/0143-module-unification.md +++ b/text/0143-module-unification.md @@ -1,5 +1,9 @@ --- +# FIXME: Is this correct? Or is it Discontinued? +Stage: Accepted Start Date: 2016-05-09 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/143 Tracking: https://github.com/emberjs/rfc-tracking/issues/27 / https://github.com/emberjs/ember.js/issues/14882 diff --git a/text/0150-factory-for.md b/text/0150-factory-for.md index b5c563cb0c..b799fc6a96 100644 --- a/text/0150-factory-for.md +++ b/text/0150-factory-for.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-06-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/150 Ember Issue: https://github.com/emberjs/ember.js/pull/14360 diff --git a/text/0176-javascript-module-api.md b/text/0176-javascript-module-api.md index 781587cf75..edb8a7b378 100644 --- a/text/0176-javascript-module-api.md +++ b/text/0176-javascript-module-api.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-11-05 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js, Ember Data, Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/176 --- diff --git a/text/0178-deprecate-ember-k.md b/text/0178-deprecate-ember-k.md index 22823e77cf..b1cc6099f9 100644 --- a/text/0178-deprecate-ember-k.md +++ b/text/0178-deprecate-ember-k.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-11-18 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Rmber.js RFC PR: https://github.com/emberjs/rfcs/pull/178 Ember Issue: https://github.com/emberjs/ember.js/issues/14746 diff --git a/text/0181-deprecate-ember-data-initializers.md b/text/0181-deprecate-ember-data-initializers.md index d40065ce83..2a8a3a0586 100644 --- a/text/0181-deprecate-ember-data-initializers.md +++ b/text/0181-deprecate-ember-data-initializers.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-11-22 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/181 --- diff --git a/text/0186-track-unique-history-location-state.md b/text/0186-track-unique-history-location-state.md index 07cf31cbe3..d33affd8d3 100644 --- a/text/0186-track-unique-history-location-state.md +++ b/text/0186-track-unique-history-location-state.md @@ -1,5 +1,9 @@ --- +Stage: Accepted Start Date: 2016-12-05 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/186 --- @@ -14,7 +18,7 @@ The path alone does not provide enough information. For example, if you visit page A, scroll down, then click on a link to page B, then click on a link back to page A. Your actual browser history stack is [A, B, A]. Each of those nodes in the history should have their own unique scroll -position. In order to record this position we need a UUID +position. In order to record this position we need a UUID for each node in the history. This API will allow other libraries to reflect upon each location to diff --git a/text/0191-deprecate-component-lifecycle-hook-args.md b/text/0191-deprecate-component-lifecycle-hook-args.md index da6dc60384..05c4804b6e 100644 --- a/text/0191-deprecate-component-lifecycle-hook-args.md +++ b/text/0191-deprecate-component-lifecycle-hook-args.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-12-14 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/191 Ember Issue: https://github.com/emberjs/ember.js/pull/14711 diff --git a/text/0194-deprecate-custom-event-manager.md b/text/0194-deprecate-custom-event-manager.md index 4bcd9a6053..4a327ec481 100644 --- a/text/0194-deprecate-custom-event-manager.md +++ b/text/0194-deprecate-custom-event-manager.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2016-12-24 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/194 Ember Issue: https://github.com/emberjs/ember.js/issues/14754 diff --git a/text/0213-custom-components.md b/text/0213-custom-components.md index ec55af36ff..d009365861 100644 --- a/text/0213-custom-components.md +++ b/text/0213-custom-components.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-03-13 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/213 Ember Issue: https://github.com/emberjs/ember.js/issues/16301 diff --git a/text/0225-ember-engines-mount-params.md b/text/0225-ember-engines-mount-params.md index 4884895489..7802cdf667 100644 --- a/text/0225-ember-engines-mount-params.md +++ b/text/0225-ember-engines-mount-params.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-04-26 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/225 Ember Issue: https://github.com/emberjs/ember.js/pull/15174 diff --git a/text/0226-named-blocks.md b/text/0226-named-blocks.md index 2984cfeb68..27e4274212 100644 --- a/text/0226-named-blocks.md +++ b/text/0226-named-blocks.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-05-05 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/226 Tracking: https://github.com/emberjs/rfc-tracking/issues/13 diff --git a/text/0229-deprecate-testing-restricted-resolver.md b/text/0229-deprecate-testing-restricted-resolver.md index 8aa60e95bc..b19a62e3b9 100644 --- a/text/0229-deprecate-testing-restricted-resolver.md +++ b/text/0229-deprecate-testing-restricted-resolver.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2017-06-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/229 --- @@ -16,14 +21,14 @@ Disabling the resolver while running tests leads to extremely brittle tests. It is not possible for collaborators to be added to the object (or one of its dependencies) under test, without modifying the test itself (even if -exactly the same API is exposed). +exactly the same API is exposed). The ability to restrict the resolver is **not** actually a feature of Ember's container/registry/resolver system, and has posed as significant maintenance challenge throughout the lifetime of ember-test-helpers. Removing this system of restriction will make choosing what kind of test to -be used easier, simplify many of the blueprints, and enable much simpler refactoring +be used easier, simplify many of the blueprints, and enable much simpler refactoring of an applications components/controllers/routes/etc to use collaborating utilties and services. @@ -31,9 +36,9 @@ and services. ## Deprecate Functionality -Issue a deprecation if `integration: true` is not included in the specified -options for the APIs listed below. This specifically includes specifying -`unit: true`, `needs: []`, or specifying none of the "test type options" +Issue a deprecation if `integration: true` is not included in the specified +options for the APIs listed below. This specifically includes specifying +`unit: true`, `needs: []`, or specifying none of the "test type options" (`unit`, `needs`, or `integration` options) to the following `ember-qunit` and `ember-mocha` API's: @@ -48,7 +53,7 @@ and `ember-mocha` API's: ### Non Component Test APIs -The migration path for `moduleFor`, `moduleForModel`, `setupTest`, and +The migration path for `moduleFor`, `moduleForModel`, `setupTest`, and `setupModelTest` is very simple: ```js @@ -77,19 +82,19 @@ moduleFor('service:session', { // before describe('Session Service', function() { setupTest('service:session'); - + // ...snip... }); describe('Session Service', function() { setupTest('service:session', { unit: true }); - + // ...snip... }); describe('Session Service', function() { setupTest('service:session', { needs: [] }); - + // ...snip... }); @@ -97,7 +102,7 @@ describe('Session Service', function() { describe('Session Service', function() { setupTest('service:session', { integration: true }); - + // ...snip... }); ``` @@ -107,7 +112,7 @@ if present). ### Component Test APIs -Implicitly relying on "unit test mode" has been deprecated for quite some time +Implicitly relying on "unit test mode" has been deprecated for quite some time ([introduced 2015-04-07](https://github.com/emberjs/ember-test-helpers/pull/38)), so all consumers of `moduleForComponent` and `setupComponentTest` are specifying one of the "test type options" (`unit`, `needs`, or `integration`). @@ -116,7 +121,7 @@ This RFC proposes to deprecate completely using `unit` or `needs` options with `moduleForComponent` and `setupComponentTest`. The vast majority of component tests should be testing via `moduleForComponent` / `setupComponentTest` with the `integration: true` option set, but on some rare occaisions it is easier to use the "unit test" style is -desired (e.g. non-rendering test) these tests should be migrated to using `moduleFor` +desired (e.g. non-rendering test) these tests should be migrated to using `moduleFor` / `setupTest` directly. ```js @@ -142,13 +147,13 @@ moduleFor('component:display-page', { // ember-mocha describe('DisplayPageComponent', function() { setupComponentTest('display-page', { unit: true }); - + // ...snip... }); describe('DisplayPageComponent', function() { setupComponentTest('display-page', { needs: [] }); - + // ...snip... }); @@ -156,7 +161,7 @@ describe('DisplayPageComponent', function() { describe('DisplayPageComponent', function() { setupTest('component:display-page', { integration: true }); - + // ...snip... }); ``` diff --git a/text/0232-simplify-qunit-testing-api.md b/text/0232-simplify-qunit-testing-api.md index 27f9e0a04d..4288f26e8b 100644 --- a/text/0232-simplify-qunit-testing-api.md +++ b/text/0232-simplify-qunit-testing-api.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-06-13 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/232 --- @@ -8,24 +12,24 @@ RFC PR: https://github.com/emberjs/rfcs/pull/232 In order to embrace newer features being added by QUnit (our chosen default testing framework), we need to reduce the brittle coupling between `ember-qunit` -and QUnit itself. +and QUnit itself. This RFC proposes a new testing syntax, that will expose QUnit API directly while -also making tests much easier to understand. +also making tests much easier to understand. # Motivation QUnit feature development has been accelerating since the ramp up to QUnit 2.0. A number of new features have been added that make testing our applications -much easier, but the current structure of `ember-qunit` impedes our ability +much easier, but the current structure of `ember-qunit` impedes our ability to take advantage of some of these features. Developers are often confused by our `moduleFor*` APIs, questions like these -are very common: +are very common: -* What "magic" is `ember-qunit` doing? -* Where are the lines between QUnit and ember-qunit? -* How can I use QUnit for plain JS objects? +* What "magic" is `ember-qunit` doing? +* Where are the lines between QUnit and ember-qunit? +* How can I use QUnit for plain JS objects? The way that `ember-qunit` wraps QUnit functionality makes the division of responsiblity much harder to understand, and leads folks to believe that there @@ -39,7 +43,7 @@ current tools were authored). Instead of things like `this.subject`, `this.regis functions in Ember via the owner API. When this RFC has been implemented and rolled out, these questions should all be -addressed and our testing system will both: embrace QUnit much more **and** +addressed and our testing system will both: embrace QUnit much more **and** be much more framework agnostic, all the while dropping custom testing only APIs in favor of public APIs that work across tests and app code. @@ -92,11 +96,11 @@ module('x-foo', function(hooks) { As you can see, this proposal leverages QUnit's nested module API in a way that makes it much clearer what is going on. It is quite obvious what QUnit is doing -(acting like a general testing framework) and what `ember-qunit` is doing +(acting like a general testing framework) and what `ember-qunit` is doing (setting up rendering functionality). -This API was heavily influenced by the work that -[Tobias Bieniek](https://github.com/Turbo87) did in +This API was heavily influenced by the work that +[Tobias Bieniek](https://github.com/Turbo87) did in [emberjs/ember-mocha#84](https://github.com/emberjs/ember-mocha/pull/84). ## QUnit Nested Modules API @@ -140,7 +144,7 @@ and `after` callbacks, and it also allows for arbitrary nesting of modules. You can read more about QUnit nested modules [here](http://api.qunitjs.com/QUnit/module#nested-module-nested-hooks-). The new APIs -proposed in this RFC expect to be leveraging nested modules. +proposed in this RFC expect to be leveraging nested modules. ## New APIs @@ -155,7 +159,7 @@ interface QUnitModuleHooks { } declare module 'ember-qunit' { - // ...snip... + // ...snip... export function setupTest(hooks: QUnitModuleHooks): void; export function setupRenderingTest(hooks: QUnitModuleHooks): void; } @@ -177,10 +181,10 @@ This function will: This function will: * run the `setupTest` implementation -* setup `this.$` method to run jQuery selectors rooted to the testing container +* setup `this.$` method to run jQuery selectors rooted to the testing container * setup a getter for `this.element` which returns the DOM element representing the element that was rendered via `this.render` -* setup Ember's renderer and create a `this.render` method which accepts a +* setup Ember's renderer and create a `this.render` method which accepts a compiled template to render and returns a promise which resolves once rendering is completed * setup `this.clearRender` method which clears any previously rendered DOM ( @@ -211,8 +215,8 @@ These changes generally do not affect our ability to write a codemod to aide in ## Migration Examples -The migration can likely be largely automated (following the -[excellent codemod](https://github.com/Turbo87/ember-mocha-codemods) that +The migration can likely be largely automated (following the +[excellent codemod](https://github.com/Turbo87/ember-mocha-codemods) that [Tobias Bieniek](https://github.com/turbo87) wrote for a similar `ember-mocha` the transition), but it is still useful to review concrete scenarios of tests before and after this RFC is implemented. @@ -313,13 +317,13 @@ moduleFor('service:flash', 'Unit | Service | Flash', { test('should allow messages to be queued', function (assert) { assert.expect(4); - + let subject = this.subject(); - + subject.show('some message here'); - + let messages = subject.messages; - + assert.deepEqual(messages, [ 'some message here' ]); @@ -332,16 +336,16 @@ import { setupTest } from 'ember-qunit'; module('Unit | Service | Flash', function(hooks) { setupTest(hooks); - + test('should allow messages to be queued', function (assert) { assert.expect(4); - + let subject = this.owner.lookup('service:flash'); - + subject.show('some message here'); - + let messages = subject.messages; - + assert.deepEqual(messages, [ 'some message here' ]); @@ -352,7 +356,7 @@ module('Unit | Service | Flash', function(hooks) { ## Ecosystem Updates -The blueprints in all official projects (and any provided by popular addons) +The blueprints in all official projects (and any provided by popular addons) will need to be updated to detect `ember-qunit` version and emit the correct output. @@ -373,8 +377,8 @@ and revamped to match the proposal here. ## Deprecate older APIs -Once this RFC is implemented, the older APIs will be deprecated and retained -for a full LTS cycle (assuming speedy landing, this would mean the older APIs +Once this RFC is implemented, the older APIs will be deprecated and retained +for a full LTS cycle (assuming speedy landing, this would mean the older APIs would be deprecated around Ember 2.20). After that timeframe, the older APIs will be removed from `ember-qunit` and `ember-test-helpers` and they will release with SemVer major version bumps. @@ -382,7 +386,7 @@ release with SemVer major version bumps. Note that while the older `moduleFor` and `moduleForComponent` APIs will be deprecated, they will still be possible to use since the host application can pin to a version of `ember-qunit` / `ember-test-helpers` that support its own -usage. This is a large benefit of migrating these testing features away from +usage. This is a large benefit of migrating these testing features away from `Ember`'s internals, and into the addon space. ## Relationship to "Grand Testing Unification" @@ -403,9 +407,9 @@ confusion, making it easier to teach and understand testing in Ember. As mentioned in [emberjs/rfcs#229](https://github.com/emberjs/rfcs/pull/229), test related churn is quite painful and annoying. In order to maintain the general -goodwill of folks, we must ensure that we avoid needless churn. +goodwill of folks, we must ensure that we avoid needless churn. -This RFC should be implemented in conjunction with +This RFC should be implemented in conjunction with [emberjs/rfcs#229](https://github.com/emberjs/rfcs/pull/229) so that we can avoid multiple back to back changes in the blueprints. diff --git a/text/0236-deprecation-ember-string.md b/text/0236-deprecation-ember-string.md index 82d5cc82f7..5b83aa59ed 100644 --- a/text/0236-deprecation-ember-string.md +++ b/text/0236-deprecation-ember-string.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-07-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/236 Tracking: https://github.com/emberjs/rfc-tracking/issues/26 diff --git a/text/0237-deprecation-ember-map.md b/text/0237-deprecation-ember-map.md index 7beef7781d..b45c9ff253 100644 --- a/text/0237-deprecation-ember-map.md +++ b/text/0237-deprecation-ember-map.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-07-20 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/237 --- diff --git a/text/0240-es-classes.md b/text/0240-es-classes.md index 4052b92a67..b9115328c7 100644 --- a/text/0240-es-classes.md +++ b/text/0240-es-classes.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-07-28 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/240 --- diff --git a/text/0252-browser-support-changes.md b/text/0252-browser-support-changes.md index 6022c4526c..4b799ff2a4 100644 --- a/text/0252-browser-support-changes.md +++ b/text/0252-browser-support-changes.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-09-25 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js, Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/252 --- @@ -32,7 +36,7 @@ Some of the features (unavailable in IE9, IE10, or PhantomJS) that addons will b - XHR advanced features ([caniuse](https://caniuse.com/#feat=xhr2), [specification](https://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/)) - HTTP2 ([caniuse](http://caniuse.com/#feat=http2), [wikipedia](https://en.wikipedia.org/wiki/HTTP/2)) - Web Workers ([caniuse](http://caniuse.com/#feat=webworkers), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)) -- IndexedDB ([caniuse](http://caniuse.com/#feat=indexeddb), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) +- IndexedDB ([caniuse](http://caniuse.com/#feat=indexeddb), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)) - WebGL ([caniuse](http://caniuse.com/#feat=webgl), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)) - File API ([caniuse](http://caniuse.com/#feat=fileapi), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/File)) - PageTransitionEvent ([caniuse](http://caniuse.com/#feat=page-transition-events), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/PageTransitionEvent)) @@ -76,7 +80,7 @@ IE10 introduced support for `requestAnimationFrame`, an efficient way to schedul When using Ember applications in IE9, IE10, or PhantomJS, Ember will cause an appropriate deprecation to be issued. The deprecation will be “until 3.0” and will reference an entry in the deprecation guide. The guide entry will describe For example: > Using Ember.js in IE9, IE10, or PhantomJS is deprecated and will be unsupported in Ember.js 3.0. We recommend using Ember’s 2.x LTS releases if your applications must support those browsers. -> +> > PhantomJS is often used for continuous integration testing. We strongly suggest adopting headless Chrome or Firefox to run CI tests. # Drawbacks diff --git a/text/0268-acceptance-testing-refactor.md b/text/0268-acceptance-testing-refactor.md index 1087d6bed9..724d7c7503 100644 --- a/text/0268-acceptance-testing-refactor.md +++ b/text/0268-acceptance-testing-refactor.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-11-05 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/268 --- @@ -58,7 +62,7 @@ that we can iterate faster while supporting multiple Ember versions independently and easily support multiple testing frameworks build on top of the primitives in `@ember/test-helpers`. Ultimately, the existing [ember-testing](https://github.com/emberjs/ember.js/tree/master/packages/ember-testing) system will be deprecated but that deprecation will be added well after the new system has been -released and adopted by the community. +released and adopted by the community. Lets take a look at a basic example (lifted from [the guides](https://guides.emberjs.com/v2.16.0/testing/acceptance/)): @@ -103,7 +107,7 @@ The following new methods will be exposed from `ember-qunit`: ```ts declare module 'ember-qunit' { - // ...snip... + // ...snip... export function setupApplicationTest(hooks: QUnitModuleHooks): void; } ``` diff --git a/text/0272-deprecation-native-function-prototype-extensions.md b/text/0272-deprecation-native-function-prototype-extensions.md index 4139ff004f..0fd25c0749 100644 --- a/text/0272-deprecation-native-function-prototype-extensions.md +++ b/text/0272-deprecation-native-function-prototype-extensions.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-11-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/272 Tracking: https://github.com/emberjs/rfc-tracking/issues/12 diff --git a/text/0276-named-args.md b/text/0276-named-args.md index bcb3e39679..bc0de41b47 100644 --- a/text/0276-named-args.md +++ b/text/0276-named-args.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-12-10 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/276 Ember Issue: https://github.com/emberjs/ember.js/pull/15968 diff --git a/text/0278-template-only-components.md b/text/0278-template-only-components.md index a987d28353..8c8f3c424a 100644 --- a/text/0278-template-only-components.md +++ b/text/0278-template-only-components.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-12-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/278 Ember Issue: https://github.com/emberjs/ember.js/pull/15974 @@ -154,8 +158,8 @@ in a few limited ways: 3. It is possible (but very rare) to configure global injections on the component type. Since no component is being instantiated here, those - properties will not be accessible in the template. - + properties will not be accessible in the template. + More broadly, `{{this.foo}}` or the shorthand `{{foo}}` (where it would have resolved into a `this` lookup) will always be `undefined` (or `null`, perhaps). diff --git a/text/0280-remove-application-wrapper.md b/text/0280-remove-application-wrapper.md index 82e0b2216c..d0b1e6552a 100644 --- a/text/0280-remove-application-wrapper.md +++ b/text/0280-remove-application-wrapper.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-12-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/280 Ember Issue: https://github.com/emberjs/ember.js/pull/15981 diff --git a/text/0281-es5-getters.md b/text/0281-es5-getters.md index c7d40f97bf..baceb4b292 100644 --- a/text/0281-es5-getters.md +++ b/text/0281-es5-getters.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-12-12 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/281 --- diff --git a/text/0286-block-let-template-helper.md b/text/0286-block-let-template-helper.md index b71b647d07..2757efc3cd 100644 --- a/text/0286-block-let-template-helper.md +++ b/text/0286-block-let-template-helper.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2017-12-21 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/286 Ember Issue: https://github.com/emberjs/ember.js/pull/16076 diff --git a/text/0287-promote-in-element-to-public-api.md b/text/0287-promote-in-element-to-public-api.md index 7ce3be4fe7..9b15c05d73 100644 --- a/text/0287-promote-in-element-to-public-api.md +++ b/text/0287-promote-in-element-to-public-api.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2017-12-22 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/287 Tracking: https://github.com/emberjs/rfc-tracking/issues/25 diff --git a/text/0293-record-data.md b/text/0293-record-data.md index 05b298860a..f96fce7a70 100644 --- a/text/0293-record-data.md +++ b/text/0293-record-data.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-01-10 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/293 Tracking: https://github.com/emberjs/rfc-tracking/issues/24 @@ -10,7 +14,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/24 Currently, incrementally experimenting with Ember Data internals is hard both for addon authors and Ember Data contributors. This RFC rationalizes the internals and establishes clear boundaries -for record data storage and manipulation allowing us to expose a public api for addon authors to experiment with. +for record data storage and manipulation allowing us to expose a public api for addon authors to experiment with. ### Motivation @@ -33,7 +37,7 @@ This RFC proposes rationalizing and extracting ED's core record data handling la #### after ![image](https://user-images.githubusercontent.com/715175/33341155-e5f170c2-d432-11e7-9c50-4a3e977331fe.png) -This will allow us to rationalize internal ED APIs, establish clearer internal boundaries, +This will allow us to rationalize internal ED APIs, establish clearer internal boundaries, allow experimentation by addon authors, and create a path for internal ED experimentation. You can think of Record Data as a layer that can receive JSON api payloads for a record, @@ -41,13 +45,13 @@ apply local changes to it, and can be queried for the current state of the data. Examples of things this would enable: -1) By shipping a custom RecordData, EmberDataModelFragments can implement a large part of their +1) By shipping a custom RecordData, EmberDataModelFragments can implement a large part of their funcionality without relying on private apis. Spike at [model fragments](https://github.com/igorT/ember-data.model-fragments/tree/igor/model-data) 2) A spike of Ember Data backed by Orbit, can be implemented as an addon, where most of the work is in implementing a Record Data backed by Orbit. Spike at [data-orbit](https://github.com/igorT/data-orbit/tree/orbit-model-data) -3) By using an ES6 class for Record Data implementation, this brings us closer to an Emberless +3) By using an ES6 class for Record Data implementation, this brings us closer to an Emberless Ember Data running. 4) If you needed to implement a GraphQL like projection API, Adapters and Serializers would be enough @@ -75,10 +79,10 @@ we can use RecordData as the main building block around which we can refactor th Ember Data would define a RecordData interface, and ship a default implementation. Addons would be able to swap their own implementation of the RecordData interface. -RecordData is an interface defining the api for how the store and DS.Models +RecordData is an interface defining the api for how the store and DS.Models store and apply changes to data. RecordDatas hold the backing data for each record, and act as a bridge between the Store, DS.Model, and Snapshots. - It is per record, and defines apis that respond to + It is per record, and defines apis that respond to store api calls like `pushData`, `adapterDidCommit` and DS.Model updates like `setAttribute`. RecordData represents the bucket of state that is backing a particular DS.Model. @@ -99,16 +103,16 @@ The interface for RecordData is: export default class RecordData { constructor(modelName: string, clientId?: string, id?: string, storeApisWrapper: StoreApisWrapper) { /* - Exposing the entire store api to the RecordData seems very risky and would + Exposing the entire store api to the RecordData seems very risky and would limit the kind of refactors we can do in the future. We would provide a wrapper - to the RecordData that would enable funcionality MD absolutely needs + to the RecordData that would enable funcionality MD absolutely needs */ } /* Hooks through which the store tells the Record Data about the data - changes. They all take JSON API and return a list of keys that the + changes. They all take JSON API and return a list of keys that the record will need to update */ @@ -177,7 +181,7 @@ export default class RecordData { getHasMany(modelName: string, id?: string, clientId?: string, key: string) { } - + addToHasMany(modelName: string, id?: string, clientId?: string, key: string, jsonApiResources, idx: number) { } @@ -202,7 +206,7 @@ export default class StoreApiWrapper { /* clientId is used as a fallback in the case of client side creation */ createRecordDataFor(modelName, id, clientId) notifyPropertyChanges(modelName, id, clientId, keys) - /* + /* in order to not expose ModelClasses to RecordData, we need to supply it with model schema information. Because a schema design is out of scope for this RFC, for now we expose these two methods we intend to deprecate once we have a schema @@ -255,7 +259,7 @@ _setupRelationships(data) { .... } ``` - + The DS.Model interactions would look like: ```js @@ -304,7 +308,7 @@ get() { } -> // Record Data returns -{[ +{[ data: { id: 5, type: 'house'}, links: { related: '/houses' }, meta: { realMetaFromServer: 'hi', _ED: { hasAllIds: true, needToLoadLink: false } } @@ -314,7 +318,7 @@ get() { ``` -ED extends the relationship payload with a custom meta, which gives the store information +ED extends the relationship payload with a custom meta, which gives the store information about whether we have information about the entire relationship (we couldn't be sure we have all the ids if we loaded from the belongsTo side) and whether the link should be refetched (we might need to refetch the link in the case it potentially changed) @@ -328,7 +332,7 @@ the backing data store let anotherHouse = store.push({data: { type: 'house', id: '5' }}); clemens.get('houses').then((houses) => { houses.pushObject(anotherHouse); - -> + -> // internally clemensRecordData.addToHasMany('houses', { data: { type: 'house', id: '5' } }) }); @@ -352,8 +356,8 @@ clemens.get('houses').then((houses) => { clemensRecordData.addToHasMany('houses', { data: { type: 'house', id: null, { meta: _ED: { clientId: 1}} } }) }); clemens.get('houses') -> -{ data: - [ { id: 5, type: 'house'}, +{ data: + [ { id: 5, type: 'house'}, { id: null, type: 'house', meta: { _ED: { clientId: 1 } } }], links: { related: '/hi' }, meta: { realMetaFromServer: 'hi', _ED: { loaded: true, needToLoadLink: false } } @@ -387,7 +391,7 @@ replacing ED's Record Data implementation ``` recordDataFor(modelName, id, options, storeWrapper) { - return new OrbitRecordData(modelName, id, storeApisWrapper) + return new OrbitRecordData(modelName, id, storeApisWrapper) } ``` @@ -396,12 +400,12 @@ recordDataFor(modelName, id, options, storeWrapper) { If a large app was loading thousands of instances of a particular record type, which was read-only, it could use a read only ED addon, which implemented a simplified RecordData without any change tracking. -The addon would implement a `recordDataFor` on the store as +The addon would implement a `recordDataFor` on the store as ``` recordDataFor(modelName, id, options, storeWrapper) { if (addonDecidesIfReadOnly(modelName)) { - return new ReadOnlyRecordData(modelName, id, storeApisWrapper) + return new ReadOnlyRecordData(modelName, id, storeApisWrapper) } return this._super(modelName, id, options, storeWrapper); } @@ -445,7 +449,7 @@ a great way to teach new addon authors about the purpose and implementation of t This change would increase the public API surface area, in a codebase that is already pretty complex. However, this would codify and simplifyA APIs addon authors have already had to interact with, while -creating a path for future simplification of the codebase. +creating a path for future simplification of the codebase. #### It allows people to do very non-standard changes that will complexify their app needlessly @@ -482,7 +486,7 @@ it's apis would not map as well to ED behavior. Our current implementation of `internalModel` is deeply monkeypatched by at least few addons. I think we have to consider it as an semi-intimate api, even though it literally has `internal` in the name(I've been told adding couple undescores to the name would have helped). Because the number of addons monkeypatching it is limited, we can manually migrate them onto the new -apis. However this requires us to make the new apis public from the get go, and doesn't allow for a long period of api evolution. +apis. However this requires us to make the new apis public from the get go, and doesn't allow for a long period of api evolution. The following options are available, none of them great: @@ -511,10 +515,10 @@ to do it in RecordDataFor or by using a singleton import. Some ceremony being re isn't super bad, because it will discourage app authors from customizing it for trivial/innapropriate things. -#### What do we do with the record state management? +#### What do we do with the record state management? Currently RecordData has no interaction with the state machine. I think we should punt on this -for now. +for now. #### { meta: { _ED: { props here } } } alternatives? diff --git a/text/0294-optional-jquery.md b/text/0294-optional-jquery.md index dfedbbff64..5db03bdddd 100644 --- a/text/0294-optional-jquery.md +++ b/text/0294-optional-jquery.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-01-11 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/294 --- @@ -8,24 +12,24 @@ RFC PR: https://github.com/emberjs/rfcs/pull/294 ## Summary -For the past Ember has been relying and depending on jQuery. This RFC proposes making jQuery optional and having a well -defined way for users to opt-out of bundling jQuery. +For the past Ember has been relying and depending on jQuery. This RFC proposes making jQuery optional and having a well +defined way for users to opt-out of bundling jQuery. ## Motivation ### Why we don't need jQuery any more -One of the early goals of jQuery was cross-browser normalization, at a time where browser support for web standards was +One of the early goals of jQuery was cross-browser normalization, at a time where browser support for web standards was incomplete and inconsistent, and Internet Explorer 6 was the dominating browser. It provided a useful and convenient API for DOM traversal and manipulation as well as event handling, that hid the various browser differences and bugs from -the user. For example `document.querySelector` wasn't a thing at that time, and browsers were using very different event -models ([DOM Level 0, DOM Level 2 and IE's own proprietary model](https://en.wikipedia.org/wiki/DOM_events#Event_handling_models)). +the user. For example `document.querySelector` wasn't a thing at that time, and browsers were using very different event +models ([DOM Level 0, DOM Level 2 and IE's own proprietary model](https://en.wikipedia.org/wiki/DOM_events#Event_handling_models)). But this level of browser normalization is not required anymore, as today's browsers all support the basic DOM APIs well enough. Even more so that the upcoming Ember 3.0 will drop support for all versions of Internet Explorer except 11. -Furthermore Ember users will need to directly traverse and modify the DOM or manually attach event listeners in very -special cases only. Most of these low level interactions are taken care of by Ember's templates and its underlying +Furthermore Ember users will need to directly traverse and modify the DOM or manually attach event listeners in very +special cases only. Most of these low level interactions are taken care of by Ember's templates and its underlying Glimmer rendering engine, as well as action helpers or the component's event handler methods. So having jQuery included by default does not provide that much value to users most of the time, and Ember itself is @@ -33,16 +37,16 @@ expected to be fully functional and tested without jQuery, presumably for the up ### What are the drawbacks of bundling jQuery -The major drawback is the increased bundle size, which amounts to [~29KB](https://mathiasbynens.be/demo/jquery-size) -(minified and gzipped). This not only increases the loading time, but also parse and compile times, thus increasing the -total time to interactive. This is especially true for mobile devices, where slow connectivity and weak CPU performance +The major drawback is the increased bundle size, which amounts to [~29KB](https://mathiasbynens.be/demo/jquery-size) +(minified and gzipped). This not only increases the loading time, but also parse and compile times, thus increasing the +total time to interactive. This is especially true for mobile devices, where slow connectivity and weak CPU performance is not uncommon. Having jQuery not included will improve the suitability of Ember for mobile applications considerably. Even if the raw number is not that huge, it all adds up. And it plays together with other efforts to make leaner Ember builds possible, like enabling tree shaking with the new [Module API](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), moving code from core to addons (e.g. the [`Ember.String` deprecation](https://github.com/emberjs/rfcs/blob/master/text/0236-deprecation-ember-string.md)) -or the ["Explode RFC"](https://github.com/emberjs/rfcs/blob/explode/text/0000-explode.md). In that regard removing the +or the ["Explode RFC"](https://github.com/emberjs/rfcs/blob/explode/text/0000-explode.md). In that regard removing the dependency on jQuery is a rather low hanging fruit with an high impact. ### But this is already possible, why this RFC? @@ -51,7 +55,7 @@ There is indeed a somewhat quirky way to build an [app without jQuery](https://g today. Although this *happens* to work, it is not sufficient to consider this officially supported for these reasons: * Ember itself must be fully tested to work without jQuery -* the public APIs that depend on and/or expose jQuery need to have some well defined behavior when jQuery is not +* the public APIs that depend on and/or expose jQuery need to have some well defined behavior when jQuery is not available * there should be a way to technically opt-out (other than fiddling with [`vendorFiles`](https://github.com/rwjblue/no-jquery-app/commit/34c40fc2cfc5e2ce0c39e5e906448c46af699d26)) that is easier to use, understand and maintain @@ -62,35 +66,35 @@ apps ### Remove internal jQuery usage -As of writing this, there are [major efforts](https://github.com/emberjs/ember.js/issues/16058) underway to remove and -cleanup the Ember codebase and especially its tests from jQuery usage. Having a way to fully test Ember without jQuery -is a prerequisite to officially support jQuery being optional. When this is done, it will enable a "no jQuery" mode, +As of writing this, there are [major efforts](https://github.com/emberjs/ember.js/issues/16058) underway to remove and +cleanup the Ember codebase and especially its tests from jQuery usage. Having a way to fully test Ember without jQuery +is a prerequisite to officially support jQuery being optional. When this is done, it will enable a "no jQuery" mode, that will make it not use jQuery anymore, but only native DOM APIs. ### Add an opt-out flag There should be a global flag that will toggle the optional jQuery integration (true by default). When this is disabled, -it will make Ember CLI's build process *not* include jQuery into the `vendor.js` bundle, *and* it will explicitly put +it will make Ember CLI's build process *not* include jQuery into the `vendor.js` bundle, *and* it will explicitly put Ember itself into its "no jQuery" mode. -The flag itself will not be made a public API. Rather it will be handled by a privileged addon, that will allow to -disable the integration flag, thus to opt out from jQuery integration. This approach is in line with -[RFC 278](https://github.com/emberjs/rfcs/pull/278) and [RFC 280](https://github.com/emberjs/rfcs/pull/280), to allow +The flag itself will not be made a public API. Rather it will be handled by a privileged addon, that will allow to +disable the integration flag, thus to opt out from jQuery integration. This approach is in line with +[RFC 278](https://github.com/emberjs/rfcs/pull/278) and [RFC 280](https://github.com/emberjs/rfcs/pull/280), to allow for some better implementation flexibility. ### Introduce `@ember/jquery` package Currently Ember CLI itself is importing jQuery into the app's `vendor.js` file. To decouple it from this task, and -to allow for some better flexibility in the future, the responsibility for importing jQuery is moved to a dedicated +to allow for some better flexibility in the future, the responsibility for importing jQuery is moved to a dedicated `@ember/jquery` addon. -To not create any breaking changes, Ember CLI will have to check the app's dependencies for the presence of this addon. +To not create any breaking changes, Ember CLI will have to check the app's dependencies for the presence of this addon. If it is not present, it will continue importing jQuery *unless* the jQuery integration flag is disabled. If it is present, it will stop importing jQuery at all, and delegate this responsibility to the addon. To nudge users to install `@ember/jquery` when they need jQuery, some warning/deprecation messages should be issued when -the addon is *not* installed and the integration flag is either not specified or is set to true. To ease -migration the addon should be placed in the default blueprint (until an eventual more aggressive deprecation of +the addon is *not* installed and the integration flag is either not specified or is set to true. To ease +migration the addon should be placed in the default blueprint (until an eventual more aggressive deprecation of jQuery). Only in the case the app is actively opting out of jQuery integration the addon is not needed. The addon itself has to make sure the Ember CLI version in use is at least the one that introduced the above mentioned @@ -98,8 +102,8 @@ logic, to prevent importing jQuery twice. ### Assertions for jQuery based APIs -Apart from testing (see below), Ember features some APIs that directly expose jQuery, which naturally cannot continue -to work without it. For these APIs some assertions have to be added when running in "no jQuery" mode (and not in +Apart from testing (see below), Ember features some APIs that directly expose jQuery, which naturally cannot continue +to work without it. For these APIs some assertions have to be added when running in "no jQuery" mode (and not in production), that provide some useful error messages for the developer: * `Ember.$()` @@ -111,28 +115,28 @@ production), that provide some useful error messages for the developer: ### Introducing `ember-jquery-legacy` and deprecating `jQuery.Event` usage Event handler methods in components will usually receive an instance of [`jquery.Event`](http://api.jquery.com/category/events/event-object/) as an argument, which is very -similar to native event objects, but not exactly the same. To name a few differences, not all properties of the native +similar to native event objects, but not exactly the same. To name a few differences, not all properties of the native event are mapped to the jQuery event, on the other hand a jquery event has a `originalEvent` property referencing the -native event. +native event. -The updated event dispatcher in Ember 3.0 is capable of working without jQuery (similar to what -`ember-native-dom-event-dispatcher` provided for Ember 2.x). When jQuery is not available, it will naturally not be -able to pass a `jquery.Event` instance but a native event instead. This creates some ambiguity for addons, as they +The updated event dispatcher in Ember 3.0 is capable of working without jQuery (similar to what +`ember-native-dom-event-dispatcher` provided for Ember 2.x). When jQuery is not available, it will naturally not be +able to pass a `jquery.Event` instance but a native event instead. This creates some ambiguity for addons, as they cannot know in advance how the consuming app is built (with or without jQuery). For code that does not rely on any `jQuery.Event` specific API, there is no need to change anything as it will continue -to work with native DOM events. +to work with native DOM events. But there are cases where jQuery specific properties have to be used (when jQuery events are passed). This is especially -true for the `originalEvent` property, for example to access `TouchEvent` properties that are not exposed on the -`jQuery.Event` instance itself. So there has to be a way to make the code work with either jQuery events or native -events being passed to the event handler (especially important for addons). Moreover this should be done in a way that +true for the `originalEvent` property, for example to access `TouchEvent` properties that are not exposed on the +`jQuery.Event` instance itself. So there has to be a way to make the code work with either jQuery events or native +events being passed to the event handler (especially important for addons). Moreover this should be done in a way that uses native DOM APIs only, to support the migration away from jQuery coupled code. To solve this issue another addon `ember-jquery-legacy` will be introduced, which for now will only expose a single `normalizeEvent` function. This function will accept a native event as well as a jQuery event (possibly distinguishing -between those two modes at build time, based on the jQuery integration flag), but will always return a native event -only. +between those two modes at build time, based on the jQuery integration flag), but will always return a native event +only. This will allow addon authors to work with both event types, but start to only use native DOM APIs: @@ -149,19 +153,19 @@ export default Component.extend({ ``` To encourage addon authors to refactor their jQuery coupled event code, the use of `jQuery.Event` specific APIs used for -jQuery events passed to component event handlers should be deprecated and a deprecation message be shown when accessing -them (e.g. `event.originalEvent`). Care must be taken though that this warning will not be issued when `normalizeEvent` -has to access `originalEvent`. +jQuery events passed to component event handlers should be deprecated and a deprecation message be shown when accessing +them (e.g. `event.originalEvent`). Care must be taken though that this warning will not be issued when `normalizeEvent` +has to access `originalEvent`. -Also for apps that do not want to transition away from jQuery and would be overloaded with unnecessary warnings, the -deprecations should be silenced when the jQuery integration flag is explicitly set to true (and not just true by +Also for apps that do not want to transition away from jQuery and would be overloaded with unnecessary warnings, the +deprecations should be silenced when the jQuery integration flag is explicitly set to true (and not just true by default). By doing so users effectively state their desire to continue using jQuery, thus any needless churn should be avoided for them. ### Testing -Ember's test harness has been based on jQuery for a long time. Most global acceptance test helpers like `find` or -`click` rely on jQuery. For integration tests the direct use of jQuery like `this.$('button').click()` to trigger +Ember's test harness has been based on jQuery for a long time. Most global acceptance test helpers like `find` or +`click` rely on jQuery. For integration tests the direct use of jQuery like `this.$('button').click()` to trigger events or assert the state of the DOM is still the standard, based on `this.$()` returning a jQuery object representing the rendered result of the tests `render` call. @@ -169,9 +173,9 @@ To be able to reliably run tests in a jQuery-less world, we need to run our test so our test harness has to work without jQuery as well. Fortunately this is well underway already. [ember-native-dom-helpers](https://github.com/cibernox/ember-native-dom-helpers) -introduced native DOM test helpers for integration and acceptance tests as an user space addon. The recent acceptance -testing [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) provides -similar test helpers, implemented in the `@ember/test-helpers` package, and envisages deprecating the global test +introduced native DOM test helpers for integration and acceptance tests as an user space addon. The recent acceptance +testing [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) provides +similar test helpers, implemented in the `@ember/test-helpers` package, and envisages deprecating the global test helpers. However while the existing jQuery based APIs are still available, when these are used without jQuery they have to throw @@ -180,63 +184,63 @@ an assertion with some meaningful error message: * global acceptance test helpers that expect jQuery selectors (which are a potentially incompatible superset of standard CSS selectors) -* `this.$()` in component tests, provided currently by `@ember/test-helpers` in `moduleForComponent` and +* `this.$()` in component tests, provided currently by `@ember/test-helpers` in `moduleForComponent` and `setupRenderingTest` In both cases the error message should state that jQuery is not available and that the native DOM based test helpers of the `@ember/test-helpers` package should be used instead. The transitioning to these new test helpers can be eased through a codemod. For `ember-native-dom-helpers` there already -exists [ember-native-dom-helpers-codemod](https://github.com/simonihmig/ember-native-dom-helpers-codemod), which +exists [ember-native-dom-helpers-codemod](https://github.com/simonihmig/ember-native-dom-helpers-codemod), which could be adapted to the very similar RFC 268 based interaction helpers in `@ember/test-helpers`. ### Implementation outline The following outlines how a possible implementation of the jQuery integration flag *could* look like. This -is just to provide some additional context, but is *intentionally not* meant to be normative, to allow some flexibility +is just to provide some additional context, but is *intentionally not* meant to be normative, to allow some flexibility for the actual implementation. The addon that will handle the flag is expected to be [ember-optional-features](https://github.com/emberjs/ember-optional-features), -which will read from and write to a `config/optional-features.{js,json}` file. This will hold the `jquery-integration` -flag (amongst others). This flag in turn will be added to the `EmberENV` hash, which will make Ember go into its -"no jQuery" mode when set to `false`. +which will read from and write to a `config/optional-features.{js,json}` file. This will hold the `jquery-integration` +flag (amongst others). This flag in turn will be added to the `EmberENV` hash, which will make Ember go into its +"no jQuery" mode when set to `false`. -Ember CLI and the `@ember/jquery` addon will also look for `jquery-integration` in this configuration file, and will +Ember CLI and the `@ember/jquery` addon will also look for `jquery-integration` in this configuration file, and will opt-out of importing jQuery when this file is present and the flag is set to `false`. ## How we teach this ### Guides -The existing "Managing Dependencies" chapters in the Ember Guides as well as on ember-cli.com provide a good place to -explain users how to set the jQuery integration flag by means of the mentioned [privileged addon](#add-an-opt-out-flag) -that handles this flag. +The existing "Managing Dependencies" chapters in the Ember Guides as well as on ember-cli.com provide a good place to +explain users how to set the jQuery integration flag by means of the mentioned [privileged addon](#add-an-opt-out-flag) +that handles this flag. -The section on components should be updated to remove any eventually remaining references to `this.$`, to not let users -fall into the trap of creating an implicit dependency on jQuery by "accidental" use of it. These should be changed to +The section on components should be updated to remove any eventually remaining references to `this.$`, to not let users +fall into the trap of creating an implicit dependency on jQuery by "accidental" use of it. These should be changed to refer to their native DOM counterparts like `this.element` or `this.element.querySelector()`. The section on acceptance tests will have been updated as per [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) to use the new `@ember/test-helpers` based test helpers instead of the jQuery based global helpers. -The section on component tests should not use `this.$()` anymore as well, and instead also according to [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) -use `this.element` to refer to the component's root element, and use the new DOM interaction helpers instead of jQuery -events triggered through `this.$()`. +The section on component tests should not use `this.$()` anymore as well, and instead also according to [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) +use `this.element` to refer to the component's root element, and use the new DOM interaction helpers instead of jQuery +events triggered through `this.$()`. ### Deprecation guide -The deprecation warnings introduced for using `jQuery.Event` specific APIs should explain the use of the -`normalizeEvent` helper function to migrate towards native DOM APIs on the one side, and on the other side the effect of +The deprecation warnings introduced for using `jQuery.Event` specific APIs should explain the use of the +`normalizeEvent` helper function to migrate towards native DOM APIs on the one side, and on the other side the effect of setting the jQuery integration flag to explicitly opt into jQuery usage thus suppressing the warnings. ### Addon migration -One of the biggest problems to easily opt-out of jQuery is that many addons still depend on it. Many of these usages -seem to be rather "accidental", in that the full power of jQuery is not really needed for the given task, and could +One of the biggest problems to easily opt-out of jQuery is that many addons still depend on it. Many of these usages +seem to be rather "accidental", in that the full power of jQuery is not really needed for the given task, and could be fairly easily refactored to use only native DOM APIs. -For this reason this RFC encourages addon authors to not use jQuery anymore and to refactor existing usages whenever -possible! This certainly does not apply categorically to all addons, e.g. those that wrap jQuery plugins as +For this reason this RFC encourages addon authors to not use jQuery anymore and to refactor existing usages whenever +possible! This certainly does not apply categorically to all addons, e.g. those that wrap jQuery plugins as components and as such cannot drop this dependency. #### ember-try @@ -249,11 +253,11 @@ sure addons don't cause errors when jQuery is not present. #### emberobserver.com -It would be very helpful to have a clear indication on [emberobserver.com](https://emberobserver.com/) which -addons depend on jQuery and which not. This would benefit users as to know which addons they can use without +It would be very helpful to have a clear indication on [emberobserver.com](https://emberobserver.com/) which +addons depend on jQuery and which not. This would benefit users as to know which addons they can use without jQuery, but also serve as an incentive for authors to make their addons work without it. -Given the jQuery integration flag introduced in this RFC, this paves the way to automatically detect addons that are +Given the jQuery integration flag introduced in this RFC, this paves the way to automatically detect addons that are basically declaring their independence from jQuery by having this flag set to `false` (in their own repository). ## Drawbacks @@ -261,14 +265,14 @@ basically declaring their independence from jQuery by having this flag set to `f ### Churn A vast amount of addons still depend on jQuery. While as far as this RFC is concerned no jQuery based APIs will be -deprecated and the default will still be to include jQuery, addons are nevertheless encouraged to remove their +deprecated and the default will still be to include jQuery, addons are nevertheless encouraged to remove their dependency on jQuery, which will add some considerable churn to the addon ecosystem. As of writing this, there are: * [475 addons](https://emberobserver.com/code-search?codeQuery=Ember.%24) using `Ember.$` * [479 addons](https://emberobserver.com/code-search?codeQuery=this.%24&fileFilter=addon%2Fcomponents) using `this.$` in components * [994 addons](https://emberobserver.com/code-search?codeQuery=this.%24&fileFilter=tests) using `this.$` in tests -Among these are still some very essential addons like `ember-data`, which still relies on `$.ajax`, see +Among these are still some very essential addons like `ember-data`, which still relies on `$.ajax`, see [#5320](https://github.com/emberjs/data/issues/5320). A good amount of that churn can be mitigated by having a codemod that migrates tests (see "Testing" above). diff --git a/text/0297-deprecate-ember-logger.md b/text/0297-deprecate-ember-logger.md index 167108746b..4901bd1dd7 100644 --- a/text/0297-deprecate-ember-logger.md +++ b/text/0297-deprecate-ember-logger.md @@ -1,5 +1,9 @@ --- -Start Date: 2018-01-17 +Stage: Recommended +Start Date: 2018-01-17 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/297 Ember Issue: https://github.com/emberjs/ember.js/issues/16231 @@ -18,16 +22,16 @@ features that are no longer needed. `Ember.Logger` came into being because the browser support for the console was inconsistent. In some browsers, like Internet Explorer 9, the console only existed when the developer tools panel was open, which caused null references and program crashes when run -with the console closed. `Ember.Logger` provided methods that would route to +with the console closed. `Ember.Logger` provided methods that would route to the console when it was available. With Ember 3.x, Ember no longer supports these older browsers, and hence this -feature no longer serves a purpose. Removing it will make Ember smaller and +feature no longer serves a purpose. Removing it will make Ember smaller and lighter. ## Detailed design -For the most part, this is a 1:1 substitution of the global `console` object +For the most part, this is a 1:1 substitution of the global `console` object for `Ember.Logger`. Node only added support for `console.debug` in Node version 9. Where we wish @@ -68,8 +72,8 @@ console.info(...arguments); ### Within the framework -Remove the following direct uses of `Ember.Logger` from the ember.js and -ember-data projects: +Remove the following direct uses of `Ember.Logger` from the ember.js and +ember-data projects: * `ember-debug`: * deprecate (`ember-debug\lib\deprecate.js`) - `Logger.warn` @@ -96,22 +100,22 @@ Note: None of the uses of `Ember.Logger` in `ember.js` or `ember-data` involve `Ember.debug`, so that issue doesn't affect the Ember.js code directly. Add deprecation warnings to the implementation: `ember-console\lib\index.js`. -Bear in mind that `Ember.deprecate` in `ember-debug` currently calls -`Logger.warn`, so the `ember-debug` code should be changed _first_ or adding +Bear in mind that `Ember.deprecate` in `ember-debug` currently calls +`Logger.warn`, so the `ember-debug` code should be changed _first_ or adding the deprecation warning will create a deep recursion. -The `Ember.assert`, `Ember.warn`, `Ember.info`, `Ember.debug`, and -`Ember.deprecate` methods suppress their output on production builds. -However, they are suppressing them in the `ember-debug` module, which -currently consumes `Ember.Logger`, _not_ by `Ember.Logger` itself. Hence, -replacing calls to `Ember.Logger` with direct calls to the console will not -affect this behavior. +The `Ember.assert`, `Ember.warn`, `Ember.info`, `Ember.debug`, and +`Ember.deprecate` methods suppress their output on production builds. +However, they are suppressing them in the `ember-debug` module, which +currently consumes `Ember.Logger`, _not_ by `Ember.Logger` itself. Hence, +replacing calls to `Ember.Logger` with direct calls to the console will not +affect this behavior. ### Add-On Developers -The following high-impact add-ons (9 or 10 or a * on EmberObserver) use -`Ember.Logger` and should probably be given an early heads-up to adjust -their code to use `console` before this RFC is implemented. This will limit +The following high-impact add-ons (9 or 10 or a * on EmberObserver) use +`Ember.Logger` and should probably be given an early heads-up to adjust +their code to use `console` before this RFC is implemented. This will limit the level of pain that their users experience when the deprecation is released. Add-ons that need to also support Ember 2.x will need to make their console @@ -125,7 +129,7 @@ In the order of their number of references to `Ember.Logger`: * `ember-stripe-service` (9) * `semantic-ui-ember` (7) * `ember-resolver` (6) -* `ember-cli-page-object` (4) +* `ember-cli-page-object` (4) * `ember-cli-sentry` (3) * `ember-islands` (3) * `ember-states` (3) @@ -144,17 +148,17 @@ For details, see https://emberobserver.com/code-search?codeQuery=Ember.Logger. ### Communication of change -We need to inform users that `Ember.Logger` will be deprecated and in what -release it will occur. +We need to inform users that `Ember.Logger` will be deprecated and in what +release it will occur. ### Official code bases and documentation -We do not currently actively teach the use of `Ember.Logger`. We will need to -remove any passing references to `Ember.Logger` from the Ember guides +We do not currently actively teach the use of `Ember.Logger`. We will need to +remove any passing references to `Ember.Logger` from the Ember guides from the Super Rentals tutorial, and anywhere else it appears on the website. -Once it is gone from the code, we also need to verify it no longer appears in -the API listings. +Once it is gone from the code, we also need to verify it no longer appears in +the API listings. We must provide an entry in the deprecation guide for this change: * describing relevant divergences remaining in the handling of the console in @@ -165,33 +169,33 @@ earlier than Node 9. ## Drawbacks -191 add-ons in Ember Inspector are using `Ember.Logger`. It has been there and -documented for a long time. So this deprecation will cause some level of change -on many projects. +191 add-ons in Ember Inspector are using `Ember.Logger`. It has been there and +documented for a long time. So this deprecation will cause some level of change +on many projects. -This, of course, can be said for almost any deprecation, and Ember's -disciplined approach to deprecation has been repeatedly shown to ease things. +This, of course, can be said for almost any deprecation, and Ember's +disciplined approach to deprecation has been repeatedly shown to ease things. These particular changes are proving easy to locate and replace by hand. Also, only twenty of those add-ons have more than six references to `Ember.Logger`. -If this is characteristic of the user base, the level of effort to make +If this is characteristic of the user base, the level of effort to make the change, even by hand, should be very small for most users. -Those using `Logger.debug` as something different from `Logger.log` may have -at least a theoretical concern. Under the covers `Logger.debug` only calls -`console.debug` if it exists, calling `console.log` otherwise. The only -platform where the difference between the two is visible in the console is on +Those using `Logger.debug` as something different from `Logger.log` may have +at least a theoretical concern. Under the covers `Logger.debug` only calls +`console.debug` if it exists, calling `console.log` otherwise. The only +platform where the difference between the two is visible in the console is on Safari. We can encourage folks with a tangible, practical concern about this to -speak up during the comment period, but I don't anticipate this will have much +speak up during the comment period, but I don't anticipate this will have much impact. ## Alternatives -1. Leave things as they are, perhaps providing an `@ember/console` module +1. Leave things as they are, perhaps providing an `@ember/console` module interface. -2. Extract `Ember.Logger` into its own (tiny) `@ember/console` package as +2. Extract `Ember.Logger` into its own (tiny) `@ember/console` package as a shim for users. ## Unresolved questions -None at this point. The answers from prior drafts have been promoted into the text. +None at this point. The answers from prior drafts have been promoted into the text. diff --git a/text/0300-rfc-process-update.md b/text/0300-rfc-process-update.md index a93d0c1402..80d12736e3 100644 --- a/text/0300-rfc-process-update.md +++ b/text/0300-rfc-process-update.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-02-04 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Steering RFC PR: https://github.com/emberjs/rfcs/pull/300 Tracking: https://github.com/emberjs/rfc-tracking/issues/1 @@ -10,7 +13,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/1 ## Summary -Refine the Ember RFC process and have it apply to all Ember teams. +Refine the Ember RFC process and have it apply to all Ember teams. ## Motivation @@ -18,7 +21,7 @@ The Ember community has been using the RFC process to great effect over the last Proposals by both Core and community members are discussed and refined with the result coming out much stronger. -During this time, the community and the core teams have identified shortcomings +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 between emberjs/rfcs and ember-cli/rfcs @@ -47,20 +50,20 @@ but this has instead given a negative impression of staleness, as RFCs linger op ### 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 ### One RFC Process for all of Ember -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. +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, +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. -Each team will be responsible for reviewing new RFCs and, if an RFC requires work from their team, ensuring that the RFC reflects that. +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 @@ -70,17 +73,17 @@ 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. 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. +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 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. + - 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. +The champion may find a replacement champion at any time. -A section on 'Finding a champion' will be added to the instructions on proposing an RFC. +A section on 'Finding a champion' will be added to the instructions on proposing an RFC. ### Introduce the concept of "FCP to close" @@ -119,20 +122,20 @@ Going forward, the numbering should be unified by virtue of having a single repo ### Track RFCs after they are accepted -At the moment it is not clear what happens to an RFC after it has been merged. +At the moment it is not clear what happens to an RFC after it has been merged. -This RFC proposes that after an RFC is merged, the relevant teams, guided by the champion, +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. -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. +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 will be updated to reflect process changes described in this RFC. +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 diff --git a/text/0308-deprecate-property-lookup-fallback.md b/text/0308-deprecate-property-lookup-fallback.md index fb80e5c30e..f95a28cad8 100644 --- a/text/0308-deprecate-property-lookup-fallback.md +++ b/text/0308-deprecate-property-lookup-fallback.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-02-15 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/308 --- diff --git a/text/0311-angle-bracket-invocation.md b/text/0311-angle-bracket-invocation.md index 862db9ceb7..bed1c1c22a 100644 --- a/text/0311-angle-bracket-invocation.md +++ b/text/0311-angle-bracket-invocation.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-03-09 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/311 --- diff --git a/text/0318-array-helper.md b/text/0318-array-helper.md index 6201342663..de19f7ef10 100644 --- a/text/0318-array-helper.md +++ b/text/0318-array-helper.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-03-24 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/318 Tracking: https://github.com/emberjs/rfc-tracking/issues/23 diff --git a/text/0322-deprecate-copy-copyable.md b/text/0322-deprecate-copy-copyable.md index b946c2e498..65f0d4fa12 100644 --- a/text/0322-deprecate-copy-copyable.md +++ b/text/0322-deprecate-copy-copyable.md @@ -1,5 +1,9 @@ --- -Start Date: 2018-03-24 +Stage: Recommended +Start Date: 2018-03-24 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/322 --- diff --git a/text/0324-deprecate-component-isvisible.md b/text/0324-deprecate-component-isvisible.md index 0b881d942f..cc2de497ad 100644 --- a/text/0324-deprecate-component-isvisible.md +++ b/text/0324-deprecate-component-isvisible.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-03-28 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/324 Tracking: https://github.com/emberjs/rfc-tracking/issues/22 @@ -8,9 +11,9 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/22 # Summary -The aim of this RFC is to deprecate the component's `isVisible` property. +The aim of this RFC is to deprecate the component's `isVisible` property. It is not used by Ember internally and left undefined unless manually set. -It's poorly documented and component visibility it better managed in +It's poorly documented and component visibility it better managed in template space rather than JS. # Motivation @@ -29,14 +32,14 @@ Simply put, removing `isVisible` will reduce confusion amongst users. # Transition Path -Whenever `isVisible` is used a deprecation will be issued with a link to +Whenever `isVisible` is used a deprecation will be issued with a link to the deprecation guide explaining the deprecation and how to refactor in order to avoid it. Given that `Component#isVisible` is a public API, deprecating now would schedule for removal in the next major version release (4.0). -There are several options available to hiding elements +There are several options available to hiding elements such as ``(hidden is valid for all elements and is semantically correct) or wrapping the component in a template conditional `{{#if}}` statement. Components `classNames` and `classNameBindings` diff --git a/text/0326-ember-data-filter-deprecation.md b/text/0326-ember-data-filter-deprecation.md index e540bbd21f..7d9e49beb9 100644 --- a/text/0326-ember-data-filter-deprecation.md +++ b/text/0326-ember-data-filter-deprecation.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-04-18 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/326 --- @@ -16,7 +21,7 @@ behind a private `ENV` variable that was enabled by the addon The `filter` API was a "memory leak by design". [Patterns exist](https://github.com/ember-data/ember-data-filter#recommended-refactor-guide) with no-worse ergonomics that have better performance and do not incur memory leak penalties. - + While the change in ergonomics for end consumers in minimal, the change to `ember-data` is substantial. The code for this feature required significant amounts of confusing internal plumbing to ensure that filters were rerun every time any form of mutation (update, addition, deletion) occurred to any record. diff --git a/text/0329-deprecated-ember-evented-in-ember-data.md b/text/0329-deprecated-ember-evented-in-ember-data.md index e4338ac4be..5a38c1c8a5 100644 --- a/text/0329-deprecated-ember-evented-in-ember-data.md +++ b/text/0329-deprecated-ember-evented-in-ember-data.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-05-01 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/329 Tracking: https://github.com/emberjs/rfc-tracking/issues/21 diff --git a/text/0331-deprecate-globals-resolver.md b/text/0331-deprecate-globals-resolver.md index 7814f44690..f9006bc73b 100644 --- a/text/0331-deprecate-globals-resolver.md +++ b/text/0331-deprecate-globals-resolver.md @@ -1,5 +1,8 @@ --- +Stage: Released Start Date: 2018-05-08 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/331 Tracking: https://github.com/emberjs/rfc-tracking/issues/20 diff --git a/text/0332-ember-data-record-links-and-meta.md b/text/0332-ember-data-record-links-and-meta.md index ec9a2fe2e9..155eacd4d7 100644 --- a/text/0332-ember-data-record-links-and-meta.md +++ b/text/0332-ember-data-record-links-and-meta.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-10-24 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/332 Tracking: https://github.com/emberjs/rfc-tracking/issues/19 @@ -17,7 +21,7 @@ Enable users to associate `links` and `meta` information with individual records Sometimes users have meta or links information to associate with a specific record. Users of the `json-api` specification will commonly understand this information as -belonging to an individual `resource`. +belonging to an individual `resource`. While `ember-data` allows for this information to exist on relationships, it does not allow for it to exist on records, which has to this point been a glaring omission @@ -110,7 +114,7 @@ let record = store.push({ data: [ { type: 'project', - id: '1', + id: '1', meta: {}, // ignored links: {} // ignored } @@ -135,7 +139,7 @@ let record = store.push({ data: [ { type: 'project', - id: '1', + id: '1', } ], meta: {}, // available on the Record's hasMany relationship diff --git a/text/0334-deprecate-ember-utils.md b/text/0334-deprecate-ember-utils.md index 6f6b5fe17f..a879cb5287 100644 --- a/text/0334-deprecate-ember-utils.md +++ b/text/0334-deprecate-ember-utils.md @@ -9,17 +9,6 @@ Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/334 --- - - # Deprecate Ember Utils & dependent Computed Properties ## Summary diff --git a/text/0335-deprecate-send-action.md b/text/0335-deprecate-send-action.md index 2ab7ad6c91..9a72cbe1f5 100644 --- a/text/0335-deprecate-send-action.md +++ b/text/0335-deprecate-send-action.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-05-29 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/335 --- @@ -96,7 +100,7 @@ export default Component.extend({ // if (this.salute) { // this.salute() // } - // + // // Alternatively, you can also define a noop salute function: // salute() {} // diff --git a/text/0337-native-class-constructor-update.md b/text/0337-native-class-constructor-update.md index 7b30e0bc63..4f7994688b 100644 --- a/text/0337-native-class-constructor-update.md +++ b/text/0337-native-class-constructor-update.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-06-14 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/337 Ember Issue: https://github.com/emberjs/ember.js/pull/16795 diff --git a/text/0340-deprecate-ember-merge.md b/text/0340-deprecate-ember-merge.md index d280bd3c87..edf01b89e9 100644 --- a/text/0340-deprecate-ember-merge.md +++ b/text/0340-deprecate-ember-merge.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-06-19 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/340 --- @@ -29,7 +33,7 @@ available to you. ## How we teach this -This should be a simple 1 to 1 conversion, and the deprecation message should be clear enough for all to +This should be a simple 1 to 1 conversion, and the deprecation message should be clear enough for all to understand what they need to do, and convert all usages of `Ember.merge` to `Ember.assign`. ### Deprecation Guide @@ -67,13 +71,13 @@ A codemod will be provided to allow automatic conversion of `Ember.merge` to `Em ## Drawbacks -The only drawback, that I can think of, is people would need to convert `Ember.merge` to +The only drawback, that I can think of, is people would need to convert `Ember.merge` to `Ember.assign`, but this would be a very easy change and could easily be done via codemod. ## Alternatives The impact of not doing this, is we continue to have two functions that do basically the same thing, -which we need to maintain. +which we need to maintain. Another alternative, could be to remove both `Ember.merge` and `Ember.assign`, in favor of `Object.assign` or something similar. diff --git a/text/0345-discord.md b/text/0345-discord.md index 0d2a5de197..181d9a7e1c 100644 --- a/text/0345-discord.md +++ b/text/0345-discord.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2019-07-11 +Release Date: FIXME +Release Versions: N/A +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/345 --- @@ -54,7 +58,7 @@ First, it has caused many of the most prolific contributors to be less active in Second, and perhaps worst of all, it undermines the transparency and open governance that we have worked hard to create. Our bar is higher than just making it possible to contribute—we go out of our way to actively welcome and encourage everyone to participate, learn and contribute. -Finally, this is not intended to replace [the forum](https://discuss.emberjs.com/), and that should be made clear. The forum is still the preferred place for asyncronous, threaded conversations where in-depth discussion is desired. +Finally, this is not intended to replace [the forum](https://discuss.emberjs.com/), and that should be made clear. The forum is still the preferred place for asyncronous, threaded conversations where in-depth discussion is desired. ## Detailed design @@ -64,9 +68,9 @@ We will need these things to transition the community smoothly: - a period of time when we use both chat platforms during the transition, put the equivalent Discord channel information in the Slack channel topic - a clear guide (with illustrations) -- once all of the setup is complete, the Discord server invites can be distributed. +- once all of the setup is complete, the Discord server invites can be distributed. -Note: the current Discord chat will be closed while this RFC is under consideration. If the RFC is accepted, then a detailed implementation plan (mostly role/channel/server setup) & invitation strategy will be carried out. +Note: the current Discord chat will be closed while this RFC is under consideration. If the RFC is accepted, then a detailed implementation plan (mostly role/channel/server setup) & invitation strategy will be carried out. #### Initial Setup @@ -74,13 +78,13 @@ Because Discord has fine-grained controls, we will be able to implement categori We intend to have the "welcome" channel as the initial channel for everyone who joins the Discord server. This channel will be read-only and will list the rules for the Discord server. -We also intend to have a "setup" channel. This channel will give you a complete guide of how to take advantage of the personalization, privacy and security, and notification controls in Discord. +We also intend to have a "setup" channel. This channel will give you a complete guide of how to take advantage of the personalization, privacy and security, and notification controls in Discord. **Verification Level** Initially, we will be implementing the "low" verification level, which means users will need to have a verified email on their Discord account. If this proves to be too easy of a target for spammers, we will implement a higher level of verification (levels include amount of time a user has to be a verified member of the server before they can post). **Explicit Content Filter** -Since this is a public Discord server, we will be setting an explicit content filter- it will scan messages from all members without a role. Email-verified members will be given a community member role to start, and other roles may be added to users over time. +Since this is a public Discord server, we will be setting an explicit content filter- it will scan messages from all members without a role. Email-verified members will be given a community member role to start, and other roles may be added to users over time. **Categories and Channels** Community members will then have the option of visiting the "setup" channel and learning more about fine-grained controls, such as: @@ -95,7 +99,7 @@ The following proposed initial category and channel list was chosen based on the **Category/Channel List:** - (No Category) - - welcome (community guidelines are posted here) <--readonly & the server invite puts users in this channel first. + - welcome (community guidelines are posted here) <--readonly & the server invite puts users in this channel first. - setup-profile (how to setup your profile) <--readonly - Admin - community-feedback (questions, comments, concerns, requests) @@ -150,13 +154,13 @@ The following proposed initial category and channel list was chosen based on the - Media (livestreams, videos, podcasts) - Pets - Women in Ember 🔒 - + **Integrations** Discord's integration game is strong. Discord has a [very detailed API](https://discordapp.com/developers/docs/intro) and many integrations already exist, and with no limitation (compared to free Slack instances, that have limited numbers of integrations). ## How do we teach this? -In addition to having a setup channel available upon login (with illustrated instructions), here are some links where community members can read more: +In addition to having a setup channel available upon login (with illustrated instructions), here are some links where community members can read more: - [Discord Loves Open Source](https://discordapp.com/open-source) - [Discord Community Guidelines](https://discordapp.com/guidelines) @@ -168,9 +172,9 @@ In addition to having a setup channel available upon login (with illustrated ins There is some concern that there is already some confusion on Slack about where to get help learning/using Ember, and where to coordinate working on Ember. We need to have a clear delineation so that the folks who are spending their volunteer time to ship Ember features can continue to concentrate and do that. -### Losing Community Members +### Losing Community Members -There is some concern that we may lose some community members due to this move. This could happen for a variety of reasons- the nature of OSS work means that some are not always active on the chat community, or the user doesn't want a different chat app, etc. We believe that the former is probably more likely than the latter, since many of us are on at least 2-3 chat apps already. +There is some concern that we may lose some community members due to this move. This could happen for a variety of reasons- the nature of OSS work means that some are not always active on the chat community, or the user doesn't want a different chat app, etc. We believe that the former is probably more likely than the latter, since many of us are on at least 2-3 chat apps already. ## Alternatives diff --git a/text/0364-roadmap-2018.md b/text/0364-roadmap-2018.md index 8cd7fb7669..4a78d3ac94 100644 --- a/text/0364-roadmap-2018.md +++ b/text/0364-roadmap-2018.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2018-08-24 +Release Date: FIXME +Release Versions: N/A +Relevant Team(s): FIXME RFC PR: https://github.com/emberjs/rfcs/pull/364 Tracking: https://github.com/emberjs/rfc-tracking/issues/28 @@ -53,7 +57,7 @@ To help us deliver a polished, cohesive experience, we will focus on two end-to- > The Core Team is in a unique position to add external-facing commentary on the framework's vision. Our RFC process and release posts are awesome, and they have done great things internally, so I would like to encourage Core to look outwards next. > —[Jen Weber](https://gist.github.com/jenweber/a9fbea98478fc3841fb8b24f7dc961c8) -> My hope is that Ember will continue to be an investment worth making. I see a growing, diverse community with lots of fresh faces as an essential part of that. +> My hope is that Ember will continue to be an investment worth making. I see a growing, diverse community with lots of fresh faces as an essential part of that. > —[Matt McManus](https://medium.com/@mattmcmanus/emberjs2018-2d28a441fadb) > Finding how and where I can help feels scattered. Issues do not receive effective labeling. This has translated into me not contributing to varying projects. @@ -68,7 +72,7 @@ To help us deliver a polished, cohesive experience, we will focus on two end-to- > A good idea would be to continue creating quests for small things like documentation, code-cleaning… And maybe add a place where this quest can be found > —[Benjamin Jegard](https://medium.com/@KamiKillertO/my-emberjs-in-2018-bc7f52739e16) -There has never been more time and energy going into Ember, but we’ve heard loud and clear that this momentum is not as visible as it needs to be. We are going to prioritize sharing work as it happens, making planning and status updates more discoverable, and making it easier for would-be contributors to get involved. +There has never been more time and energy going into Ember, but we’ve heard loud and clear that this momentum is not as visible as it needs to be. We are going to prioritize sharing work as it happens, making planning and status updates more discoverable, and making it easier for would-be contributors to get involved. We also need to double down on making Ember as friendly and inclusive as possible, particularly for folks who have never participated in an open source project before. As we bring in new community members, we will make changes to ensure that individuals can have a meaningful impact, no matter what time zone they live in. diff --git a/text/0369-deprecate-computed-clobberability.md b/text/0369-deprecate-computed-clobberability.md index 2a675b8300..5c8a560664 100644 --- a/text/0369-deprecate-computed-clobberability.md +++ b/text/0369-deprecate-computed-clobberability.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-08-30 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/369 Tracking: https://github.com/emberjs/rfc-tracking/issues/18 diff --git a/text/0370-deprecate-computed-volatile.md b/text/0370-deprecate-computed-volatile.md index a97da12900..a3ef7075d1 100644 --- a/text/0370-deprecate-computed-volatile.md +++ b/text/0370-deprecate-computed-volatile.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-08-31 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/370 Tracking: https://github.com/emberjs/rfc-tracking/issues/17 diff --git a/text/0372-ember-data-model-factory-for.md b/text/0372-ember-data-model-factory-for.md index 709568287c..8f2948af35 100644 --- a/text/0372-ember-data-model-factory-for.md +++ b/text/0372-ember-data-model-factory-for.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-09-06 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/372 Tracking: https://github.com/emberjs/rfc-tracking/issues/16 @@ -21,7 +25,7 @@ Ember differentiates between `klass` and `factory` for classes registered with t `ember-data` has carried two APIs for accessing one or the other for some time. The public `modelFor` provides access to the `klass` where schema information is stored, while the private `_modelFactoryFor` provides access to the factory for instantiation. - + We provide access to the class with `modelFor` roughly implemented as `store._modelFactoryFor(modelName).klass`. We instantiate records from this class roughly implemented as `store._modelFactoryFor(modelName).create({ ...args })`. @@ -81,14 +85,14 @@ export default Store.extend({ if (someCustomCondition) { return getOwner(this).factoryFor(someFactoryName); } - + return this._super(modelName); } }); ``` - + #### `Model.modelName` - + `ember-data` currently sets `modelName` onto the `klass` accessible via the `factory`. For classes that do not inherit from `DS.Model` this would not be done, although end users may do so themselves in their implementations if so desired. @@ -99,7 +103,7 @@ The default export of a custom ModelClass **MUST** conform to the requirements o of `factoryFor` are currently underspecified; however, in practice, this means that the default export is an instantiable class with a static `create` method and an instance `destroy` method or that inherits from `EmberObject` (which provides such methods). - + **Example 2:** ```javascript @@ -132,7 +136,7 @@ export default class CustomModel extends EmberObject { Custom classes for models should expect their constructor to receive a single argument: an object with *at least* the following. - + - A `recordData` instance accessible via `getRecordData` (see below) - Any properties passed as the second arg to `createRecord` - An `owner` accessible via `Ember.getOwner` @@ -143,11 +147,11 @@ Custom classes for models should expect their constructor to receive a single ar Every `record` (instance of the class returned by `modelFactoryFor`) will have an associated [RecordData](https://github.com/emberjs/rfcs/pull/293) which contains the backing data for the id, type, attributes and relationships of that record. - + This backing data can be accessed by using the `getRecordData` util on the `record` (or on the `createArgs` passed to a record). Using `getRecordData` on a `record` is only guaranteed after the record has been instantiated. During instantiation, this call should be made on the `createArgs` object passed into the record. - + **Example 4** ```javascript diff --git a/text/0373-Element-Modifier-Managers.md b/text/0373-Element-Modifier-Managers.md index 7f1e7b937f..bf427479b6 100644 --- a/text/0373-Element-Modifier-Managers.md +++ b/text/0373-Element-Modifier-Managers.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-09-10 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/373 --- diff --git a/text/0375-deprecate-computed-property-modifier.md b/text/0375-deprecate-computed-property-modifier.md index ad37a15b79..e3129dabb5 100644 --- a/text/0375-deprecate-computed-property-modifier.md +++ b/text/0375-deprecate-computed-property-modifier.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-09-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/375 Tracking: https://github.com/emberjs/rfc-tracking/issues/15 diff --git a/text/0386-remove-jquery.md b/text/0386-remove-jquery.md index 56c3b9600c..931f079f0f 100644 --- a/text/0386-remove-jquery.md +++ b/text/0386-remove-jquery.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-10-07 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/386 Tracking: https://github.com/emberjs/rfc-tracking/issues/3 @@ -11,7 +14,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/3 ## Summary This RFC proposes deprecating those public APIs that are coupled to jQuery, and to finally remove them (with an optional -backport), so Ember apps will be built *by default* without bundling jQuery. +backport), so Ember apps will be built *by default* without bundling jQuery. While [RFC294](https://emberjs.github.io/rfcs/0294-optional-jquery.html), which is already implemented, provides a way to opt out of jQuery, the intention of this RFC is to push this a step further and essentially move from the @@ -23,30 +26,30 @@ In that way it is not meant as a replacement of the previous RFC, but rather as ### Lean by default -This follows the philosophy of making Ember leaner (or *higher octane* if you want), by deprecating unused or +This follows the philosophy of making Ember leaner (or *higher octane* if you want), by deprecating unused or non-essential APIs. New apps will be smaller and faster by default, while allowing to opt-in into using jQuery when needed. ### Why the current opt-out strategy is not sufficient The biggest problem in the current opt-out strategy is that many addons still require jQuery. Many of these usages -seem to be rather "accidental", in that the full power of jQuery is not really needed for the given task, and could be -rather easily refactored to use only native DOM APIs. But as it is available anyway by default, and it is very convenient, -authors probably tend to use it without being fully aware of the consequences, that it prohibits jQuery-less builds for +seem to be rather "accidental", in that the full power of jQuery is not really needed for the given task, and could be +rather easily refactored to use only native DOM APIs. But as it is available anyway by default, and it is very convenient, +authors probably tend to use it without being fully aware of the consequences, that it prohibits jQuery-less builds for all its consumers. -In that way the general availability of jQuery *by default* and Ember APIs around it like `this.$()` tend to manifest the +In that way the general availability of jQuery *by default* and Ember APIs around it like `this.$()` tend to manifest the status quo, the coupling of Ember to jQuery. In fact I could observe an actual *increase* of jQuery usage numbers -(see below), rather than a decrease, which was an intention of the previous RFC. So it is not only a concern of the core +(see below), rather than a decrease, which was an intention of the previous RFC. So it is not only a concern of the core Ember library to enable jQuery-less builds, but the whole addon ecosystem has to go through that transition. In that regard early deprecations will help prevent this accidental use of jQuery on the one side, and on the other side -for addons that depend on jQuery already they will provide an incentive and a long enough transition period to refactor +for addons that depend on jQuery already they will provide an incentive and a long enough transition period to refactor their jQuery usage to use standard DOM APIs. ### jQuery might still be needed -This RFC does not propose to discourage the use of jQuery. There are legitimate cases where you still want to have it. +This RFC does not propose to discourage the use of jQuery. There are legitimate cases where you still want to have it. And this is also true for addons, especially those that basically wrap other jQuery-based libraries like jQuery plugins in an Ember friendly way. For those cases, there should be an *opt-in* path to continue bundling jQuery and to preserve the existing APIs around it. This is what the `@ember/jquery` package is meant for. @@ -55,31 +58,31 @@ the existing APIs around it. This is what the `@ember/jquery` package is meant f ### Add deprecations -All current public APIs that are coupled to jQuery should be deprecated via the usual deprecation process. +All current public APIs that are coupled to jQuery should be deprecated via the usual deprecation process. This specifically involves: * adding a (universal, non-silenceable) deprecation warning to `Ember.$()` * adding a deprecation warning to `this.$()` in an `Ember.Component` -* adding a deprecation warning to `this.$()` in component integration tests, based on `setupRenderingTest()` +* adding a deprecation warning to `this.$()` in component integration tests, based on `setupRenderingTest()` ### `this.$()` in old style tests -`this.$()` in tests based on the old `moduleForComponent()` based testing APIs will not be specifically deprecated, +`this.$()` in tests based on the old `moduleForComponent()` based testing APIs will not be specifically deprecated, as these legacy testing APIs will eventually be deprecated altogether, as already envisaged in RFC232. ### Extend `@ember/jquery` package For apps and addons that have to or choose to still require jQuery, they can add this package to its dependencies. -This will provide a way to retain the deprecated and later removed APIs. So by adding this to your dependencies this +This will provide a way to retain the deprecated and later removed APIs. So by adding this to your dependencies this would effectively be the way to *opt-in* to require jQuery. RFC294 already introduced this package, being responsible to include jQuery into the JavaScript bundle. As part of this -RFC the scope of this addon will be extended to also reintroduce the deprecated APIs, but *without* triggering any +RFC the scope of this addon will be extended to also reintroduce the deprecated APIs, but *without* triggering any deprecation warnings for `this.$()` in a component. -As the default `EventDispatcher`, which currently dispatches jQuery events when jQuery is enabled, will eventually +As the default `EventDispatcher`, which currently dispatches jQuery events when jQuery is enabled, will eventually support native events only (see the Timeline below), the addon also needs to replace it with one that again dispatches -jQuery events for compatibility with existing jQuery-based code. This can happen in a similar way as +jQuery events for compatibility with existing jQuery-based code. This can happen in a similar way as [ember-native-dom-event-dispatcher](https://github.com/rwjblue/ember-native-dom-event-dispatcher) did it, just the other way around. @@ -87,38 +90,38 @@ way around. the burden to care about this.** So effectively, for the Ember 3.x release cycle, adding this package will not change the behavior in any significant way, -other than removing the mentioned deprecation warnings, as Ember will still have these APIs available. However starting -with Ember 4.0, which will have these APIs removed and not include jQuery integration features anymore, this +other than removing the mentioned deprecation warnings, as Ember will still have these APIs available. However starting +with Ember 4.0, which will have these APIs removed and not include jQuery integration features anymore, this package will make sure jQuery remains included and it will add the now removed APIs back again, so any jQuery depending code will continue to work just as before. Also see the timeline below. As `ember-cli-babel` will currently transform `import $ from 'jquery';` to use `Ember.$` again, it must be made aware of -the `@ember/jquery` package so it tells `babel-plugin-ember-modules-api-polyfill` not to convert those imports to the +the `@ember/jquery` package so it tells `babel-plugin-ember-modules-api-polyfill` not to convert those imports to the global `Ember.$`. Instead the package itself should provide the necessary shim to make `import $ from 'jquery';` work. -Addons that continue to depend on jQuery would have to list this package as a dependency in their `package.json`, +Addons that continue to depend on jQuery would have to list this package as a dependency in their `package.json`, to make their consuming app automatically include jQuery and the related APIs in its bundle as mentioned above. -Thereby they make their dependency on jQuery explicit, which in turn helps users to make an educated choice if they +Thereby they make their dependency on jQuery explicit, which in turn helps users to make an educated choice if they deem this to be acceptable. ### Extend ember-fetch The `ember-fetch` addon integrates the newer [`Fetch API`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) nicely into an Ember app, with an (optional) polyfill for older browsers. This can be used as a replacement for the -jQuery-based `ember-ajax`. +jQuery-based `ember-ajax`. One piece that is missing so far when switching is a convenient way to customize all outgoing requests, e.g. to add HTTP headers for authentication tokens. When using jQuery's AJAX implementation, this could be easily done using its -[`prefilter`](http://api.jquery.com/jquery.ajaxprefilter/) function. To facilitate something similar when using -`ember-fetch`, the addon should be extended with an appropriate API, e.g. by adding a simple service through which +[`prefilter`](http://api.jquery.com/jquery.ajaxprefilter/) function. To facilitate something similar when using +`ember-fetch`, the addon should be extended with an appropriate API, e.g. by adding a simple service through which fetch requests are issued, which provides similar features for customization. The exact API of such a service is however out of scope for this RFC. ### Make ember-data use ember-fetch It must be ensured that all parts of the core Ember experience work flawlessly without jQuery. Currently `ember-data` -is still relying on jQuery for its XHR requests. By the time this RFC is implemented (i.e. the deprecation messages are -added), it must work out of the box without jQuery. +is still relying on jQuery for its XHR requests. By the time this RFC is implemented (i.e. the deprecation messages are +added), it must work out of the box without jQuery. Fortunately [migration efforts](https://github.com/emberjs/data/pull/5386) are well advanced to support the `fetch` API through `ember-fetch`, so we can expect that to land soon enough that it does not block the transition. @@ -145,20 +148,20 @@ Upon Ember 4.0 ## How we teach this -As part of the efforts to make jQuery optional, the guides have already been updated to have all examples teach native -DOM APIs instead of jQuery, and the new testing APIs. +As part of the efforts to make jQuery optional, the guides have already been updated to have all examples teach native +DOM APIs instead of jQuery, and the new testing APIs. The [jQuery migration guide](https://guides.emberjs.com/release/configuring-ember/optional-features/#toc_jquery-integration) already mentions the APIs that are not available anymore without jQuery and how to opt-out now. Activating the `no-jquery` ESLint rule will warn developers about any usages of the jQuery-based APIs being deprecated -here. +here. The newly added deprecation messages should link to a deprecation guide, which will provide details on how to silence -these deprecations, either by using native DOM APIs only or by installing `@ember/jquery` to explicitly opt-in into -jQuery. +these deprecations, either by using native DOM APIs only or by installing `@ember/jquery` to explicitly opt-in into +jQuery. For apps the tone of it should be neutral regarding jQuery itself, in the sense that using jQuery is neither -bad nor good by itself. It depends on the context of the app if using jQuery makes sense or not. It is just that *Ember* +bad nor good by itself. It depends on the context of the app if using jQuery makes sense or not. It is just that *Ember* does no need it anymore, so it is not part of the default Ember experience anymore. For addons the story is a bit different, in that they are not aware of their app's context, so they should abstain from @@ -176,8 +179,8 @@ ecosystem. As of writing this, there are: A good amount of that churn can be mitigated by * existing codemods that migrate tests -* having an easy way, given by the `@ember/jquery` package, to opt-in to continue bundling jQuery, and to restore the -deprecated APIs, so no further refactorings are required +* having an easy way, given by the `@ember/jquery` package, to opt-in to continue bundling jQuery, and to restore the +deprecated APIs, so no further refactorings are required ## Alternatives diff --git a/text/0389-dynamic-tag-names.md b/text/0389-dynamic-tag-names.md index 9edd521322..7e127ad97a 100644 --- a/text/0389-dynamic-tag-names.md +++ b/text/0389-dynamic-tag-names.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-10-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/389 Tracking: https://github.com/emberjs/rfc-tracking/issues/42 diff --git a/text/0391-router-helpers.md b/text/0391-router-helpers.md index d89f8e1a6e..16a68574e2 100644 --- a/text/0391-router-helpers.md +++ b/text/0391-router-helpers.md @@ -1,6 +1,10 @@ --- +Stage: Accepted Start Date: 2018-10-22 Relevant Team(s): Ember.js +Release Date: Unreleased +Release Versions: Unreleased +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/391 Tracking: https://github.com/emberjs/rfc-tracking/issues/14 diff --git a/text/0392-deprecate-component-manager-string-lookup.md b/text/0392-deprecate-component-manager-string-lookup.md index ad4949b6fc..10a175d514 100644 --- a/text/0392-deprecate-component-manager-string-lookup.md +++ b/text/0392-deprecate-component-manager-string-lookup.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-10-23 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/392 --- diff --git a/text/0395-ember-data-packages.md b/text/0395-ember-data-packages.md index c373fc7f39..832b4ac8ec 100644 --- a/text/0395-ember-data-packages.md +++ b/text/0395-ember-data-packages.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-10-31 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/395 Tracking: https://github.com/emberjs/rfc-tracking/issues/11 diff --git a/text/0398-RouteInfo-Metadata.md b/text/0398-RouteInfo-Metadata.md index ea7b66977d..410073ec53 100644 --- a/text/0398-RouteInfo-Metadata.md +++ b/text/0398-RouteInfo-Metadata.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-11-02 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/398 Tracking: https://github.com/emberjs/rfc-tracking/issues/10 diff --git a/text/0403-ember-data-identifiers.md b/text/0403-ember-data-identifiers.md index 9de0aebbf3..191af2cc55 100644 --- a/text/0403-ember-data-identifiers.md +++ b/text/0403-ember-data-identifiers.md @@ -1,12 +1,16 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-11-25 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/403 Tracking: https://github.com/emberjs/rfc-tracking/issues/31 --- -# Ember Data | Identifiers +# Ember Data | Identifiers ## Summary @@ -24,44 +28,44 @@ In doing so we provide a framework for future RFCs and/or addons to address many ## Motivation -This groundwork RFC represents the union of a diverse set of motivations, each of which - is discussed below in no particular order of importance, outside of the first. **This +This groundwork RFC represents the union of a diverse set of motivations, each of which + is discussed below in no particular order of importance, outside of the first. **This RFC is not seeking to immediately address each of the motivations below, we are adding infrastructure to make future RFCs possible in these spaces** ### Unified concept of Identity Identity is a core concept to managing a cache and guaranteeing [atomicity, consistency, - isolation, and durability](https://en.wikipedia.org/wiki/ACID_(computer_science)). - Currently, `ember-data` has no unified mechanism for Identity. This missing mechanism - introduces errors in application code, makes `ember-data` internals needlessly complex, + isolation, and durability](https://en.wikipedia.org/wiki/ACID_(computer_science)). + Currently, `ember-data` has no unified mechanism for Identity. This missing mechanism + introduces errors in application code, makes `ember-data` internals needlessly complex, and complicates the method signatures of many public APIs. -Creating a unified `Identity` concept will allow `ember-data` to expose `identity` as a -first-class primitive to our users, improving the mental model, improving application -resiliance to errors, and providing a clear language of communication between `ember-data`'s +Creating a unified `Identity` concept will allow `ember-data` to expose `identity` as a +first-class primitive to our users, improving the mental model, improving application +resiliance to errors, and providing a clear language of communication between `ember-data`'s various primitives. Today, we handle `identity` in a myriad of ad-hoc ways: * `InternalModel` instances as keys for most internal methods and the relationship layer. * `type+id` for serializing/deserializing a `record` or [`resource`](https://jsonapi.org/format/#document-resource-object-identification) -* `type+clientId` for caching newly created records on the client and communicating +* `type+clientId` for caching newly created records on the client and communicating about them with `RecordData`. -* Various other non-serializable forms of identity for tracking requests, relationship +* Various other non-serializable forms of identity for tracking requests, relationship membership and state. -* In some cases we have no concept at all where one is needed (for instance, caching +* In some cases we have no concept at all where one is needed (for instance, caching queries) We wish to simplify and codify our handling of identity. ### Simplify StoreWrapper and RecordData APIs -Today, to deal with the lack of a unified `identifier` concept, we overload many +Today, to deal with the lack of a unified `identifier` concept, we overload many `StoreWrapper` and `RecordData` API method signatures with `modelName`, `id`, `clientId` as arguments. This leads to method signatures being long and needlessly unwieldy. -Note: We had initially intended to overload all of these classes method signatures in +Note: We had initially intended to overload all of these classes method signatures in this way, to ensure that `RecordData` implementations could be `singleton`s, but we failed to correctly implement the `RecordData` RFC in this regard and a near future RFC will look at rectifying this using the `Identity` APIs introduced here. @@ -71,13 +75,13 @@ Moving to a unified concept of `identity` opens up a path to clean up these meth ### Operations -Operations are a foundational concept for `acid` transactions. Without the ability to +Operations are a foundational concept for `acid` transactions. Without the ability to describe an operation and a clear mental model of what operations exist and achieve, it is difficult to understand how an action affects state. Granularity and clarity is key. While `ember-data` does not yet have concepts of operations or transactions, mutations and updates are applied directly, there are many areas we could improve upon by introducing -them. As with data, operations upon data should be serializable so that local state can +them. As with data, operations upon data should be serializable so that local state can be accurately cached on local clients. ### Nested Saves / API Transactions / Websocket Support @@ -87,23 +91,23 @@ Many applications wish to create or update and save multiple records together. A is correctly matching data received back from the API to the newly created records already on the client. -A similar edge case occurs when a newly created record is saved for the first time and +A similar edge case occurs when a newly created record is saved for the first time and prior to receiving the request response the same record is recieved via another means (background polling, websocket subscription, etc.). We have no means of matching the record -returned by the alternative means to that of the request, leading to a second cache entry +returned by the alternative means to that of the request, leading to a second cache entry being created and an error once the initial request completes. One solution has been to generate and assign `id`s for records on the client, but this is not always desireable. These scenarios are a major motivation for `lid` in the `json-api` -spec. Users wishing to solve these cases would be able to serialize the `lid` of the -`Identifier` for a newly created record and reflect that `lid` back in any payloads send +spec. Users wishing to solve these cases would be able to serialize the `lid` of the +`Identifier` for a newly created record and reflect that `lid` back in any payloads send from their API for the session to correctly match the payloads to the record. ### Better Cache Serialization & Improved Infra for Offline Support -In order to enable users to achieve full offline support, or to serialize the store +In order to enable users to achieve full offline support, or to serialize the store or transport across the wire (for example as an advanced fastboot rehydration mode) -the entire state of the store needs to be serializable. This RFC introduces the +the entire state of the store needs to be serializable. This RFC introduces the foundation for mechanisms through which this can be later achieved. ---- @@ -122,20 +126,20 @@ export interface RecordIdentifier extends Identifier { ``` Note: the referential stability (object reference) of all identifiers created by the -`store` is guaranteed. E.g. any data that results in the lookup of an identifier -producing the same `lid` token will return the same `Identifier` instance. This is +`store` is guaranteed. E.g. any data that results in the lookup of an identifier +producing the same `lid` token will return the same `Identifier` instance. This is useful for being able to use identifiers for either `Map` or `WeakMap` cache solutions. ### Buckets In an ideal world, the `lid` of each `Identifier` would be a `v4` [uuid](https://en.wikipedia.org/wiki/Universally_unique_identifier), making it practically unique in all contexts. However, due to requirements around design - flexibility and performance we are only requiring that `Identifiers` be unique _within + flexibility and performance we are only requiring that `Identifiers` be unique _within their bucket_ for the data they are intended to reference. Each underlying primitive will have its own bucket, as new primitives are formalized, new buckets will emerge. Initially we expect only a `record` bucket which aligns with today's -`IdentityMap` cache for `Record`s. Examples of future buckets may include a cache for +`IdentityMap` cache for `Record`s. Examples of future buckets may include a cache for `queries`, `documents`, `transactions`, `operations`, `errors`, `meta` or any number of other concepts that represent state required to be serializable. @@ -148,12 +152,12 @@ In our ideal world, the `lid` would then be a `uuid-v4` that is practically uniq rendering. This cost is primarily due to the need to generate large quantities of random bytes: a cost - that is necessarily cpu intensive. Additionally, many forms of data (such as `json-api` + that is necessarily cpu intensive. Additionally, many forms of data (such as `json-api` resources) come with unique or nearly unique identifying information already (`type` + `id`, `href` etc.). Some APIs already make use of `v4` `uuid`s as IDs, and for these APIs it would make the most sense to implement a custom generation method to reuise these `id`s as `lid`s when present. - + To balance performance with the requirements of `identity`, we are choosing what we feel is a *sensible default*. Users for whom this default does not meet their requirements may override the appropriate hooks to generate identifiers that do. @@ -177,7 +181,7 @@ Indeed in this vein, we have not provided a mechanism for distinguishing what in using this availability to affect your generation method. Supplying custom `lid` generation can be done using `setIdentifierGenerationMethod`. Currently - there is only one bucket (`record`) as discussed above, but we reserve the ability to add + there is only one bucket (`record`) as discussed above, but we reserve the ability to add additional buckets in the future. Users should do any identifier customization within an instance-initialize prior to making use @@ -198,7 +202,7 @@ Users should do any identifier customization within an instance-initialize prior The method must return a unique (to at-least the given bucket) string identifier for the given data as a string to be used as the `lid` of an `Identifier` token. - This method will only be called by either `getOrCreateIdentifier` or + This method will only be called by either `getOrCreateIdentifier` or `createIdentifierForNewRecord` when an identifier for the supplied data is not already known via `lid` or `type + id` combo and one needs to be generated or retrieved from a proprietary cache. @@ -218,7 +222,7 @@ type GenerationMethod = (data: Object, bucket: string) => string; This method is called everytime `updateRecordIdentifier` is called and with the same arguments. It provides the opportunity to update secondary lookup tables for existing identifiers. - + It will always be called after an identifier created with `createIdentifierForNewRecord` has been committed, or after an update to the `record` a `RecordIdentifier` is assigned to has been committed. Committed here meaning that the server @@ -278,8 +282,8 @@ export default { ### Identifiers for Records -When discussing identifiers for records it is useful to be familiar with `json-api` -interfaces for [ResourceObjects](https://jsonapi.org/format/#document-resource-objects) +When discussing identifiers for records it is useful to be familiar with `json-api` +interfaces for [ResourceObjects](https://jsonapi.org/format/#document-resource-objects) and [ResourceIdentifierObjects](https://jsonapi.org/format/#document-resource-identifier-objects). Below, we expose a rough approximation of these interfaces as `Resource` including the @@ -336,7 +340,7 @@ export default class IdentifierCache extends Service { /* Provides the opportunity to update secondary lookup tables for existing identifiers - + Called with the attributes provided to createRecord after an identifier created with `createIdentifierForNewRecord` has been instantiated. @@ -370,14 +374,14 @@ let identifierA = identifierCache.getOrCreateRecordIdentifier({ let identifierB = identifierCache.getOrCreateRecordIdentifier({ type: 'foo', id: '2', - lid: '123a' + lid: '123a' }); // => { lid: '123a' } -let identifierC = identifierCache.getOrCreateRecordIdentifier({ - type: 'foo', - lid: '123b' +let identifierC = identifierCache.getOrCreateRecordIdentifier({ + type: 'foo', + lid: '123b' }); // => { lid: '123b' } -let identifierD = identifierCache.getOrCreateRecordIdentifier({ - lid: '123c' +let identifierD = identifierCache.getOrCreateRecordIdentifier({ + lid: '123c' }); // => { lid: '123c' } // ... generating identifiers for newly created resources @@ -390,9 +394,9 @@ let identifier3 = identifierCache.createIdentifierForNewRecord('bar'); // => { l ### Updating new record Identifiers with more complete information Called when an identifier has been generated for resource data prior to `id` being - available for that resource and complete resource data is now available. `ember-data` + available for that resource and complete resource data is now available. `ember-data` will automatically call this with the resolved payload after save for any newly created - records. An `identifier` can only be updated once, and only when transitioning the + records. An `identifier` can only be updated once, and only when transitioning the associated resource from a never-before-persisted to persisted state. Udating provides the opportunity to update the primary and secondary lookup tables for the @@ -453,7 +457,7 @@ Whether and how to access an identifier during instantiation of a record will be A common edge case that `Identifiers` enables end users to solve is when multiple pieces of identifying information should reference the same data. - + For instance, when using single-table polymorphism (in which `ferrari` and `bmw` extend `car` and share a common `id` space) then `ferrari:1` and `bmw:2` are the same vehicles as `car:1` and `car:2`. @@ -462,8 +466,8 @@ A similar problem presents for the scenario in which we know that we wish to ref `user` with a given `username`, but do not yet have access to the `id` for that user. In this case, `user:@jackson5` and `user:abc123` are the same user. -Today in these situations many users will encounter bugs resulting from there being two - records present in the cache instead of one. This problem can be solved with a custom +Today in these situations many users will encounter bugs resulting from there being two + records present in the cache instead of one. This problem can be solved with a custom identifier generation method that is aware of an application's polymorphic associations or additional indexing requirements. @@ -491,7 +495,7 @@ export function initialize(applicationInstance) { setIdentifierGenerationMethod((resource: Resource) => { let { type, id, lid } = resource; - let username = (resource.type === 'user' + let username = (resource.type === 'user' && resource.attributes && resource.attributes.username); let cacheKey, altCacheKey; @@ -540,8 +544,8 @@ export default { ``` #### Handling Updates to Alternative Cache Keys - - Note that in our above example we treat `username` a stable, immutable alternative + + Note that in our above example we treat `username` a stable, immutable alternative primary-key. Some APIs allow users to change the value of such "unique keys" (`email` `phone` `username` being common examples). @@ -561,7 +565,7 @@ export default { export function updateUsernameForIdentifier( // application instance is the result of `getOwner` // on something like the `store` or a `component` - owner: Owner, + owner: Owner, identifier: Identifier, oldUsername: string, newUsername: string @@ -585,7 +589,7 @@ export default { ### Identifier Stability Identifiers handed to public APIs by `ember-data` will **always** be _referentially stable_ - Public `ember-data` APIs that **expect** an `Identifier` will normalize the object they + Public `ember-data` APIs that **expect** an `Identifier` will normalize the object they are given into the stable `Identifier` if it is not one already. This is done to allow for serialized identifiers and identifying information from the API to more easily be worked with without extra normalization effort. @@ -650,9 +654,9 @@ a multitude of benefits, including: * **debugging:** enhanced debugging by associating additional information with the identifier in development builds -* **debugging:** enhanced debugging by users being able to see type and id at a +* **debugging:** enhanced debugging by users being able to see type and id at a glance when inspecting state. -* **bug prevention:** enforcement of the use of the identifier generation process +* **bug prevention:** enforcement of the use of the identifier generation process (to ensure lookup tables are properly populated) * **debugging:** ability to tell at a glance that an identifier was properly processed * **ergonomics:** closer alignment to `jsonapi` that makes it true that all `RecordIdentifiers` diff --git a/text/0408-decorators.md b/text/0408-decorators.md index b914f894db..5f64b184bb 100644 --- a/text/0408-decorators.md +++ b/text/0408-decorators.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-10-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/408 Tracking: https://github.com/emberjs/rfc-tracking/issues/7 diff --git a/text/0410-tracked-properties.md b/text/0410-tracked-properties.md index eb16e9bbf1..0daee6e3a8 100644 --- a/text/0410-tracked-properties.md +++ b/text/0410-tracked-properties.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-12-05 +Release Date: FIXME +Release Versions: FIXME RFC PR: https://github.com/emberjs/rfcs/pull/410 Relevant Team(s): Ember.js Authors: Tom Dale, Chris Garrett, Chad Hietala, Yehuda Katz diff --git a/text/0415-render-element-modifiers.md b/text/0415-render-element-modifiers.md index 2efce7449b..8a038b59ca 100644 --- a/text/0415-render-element-modifiers.md +++ b/text/0415-render-element-modifiers.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-12-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/415 Tracking: https://github.com/emberjs/rfc-tracking/issues/8 diff --git a/text/0416-glimmer-components.md b/text/0416-glimmer-components.md index 7bd42be9bf..ec0e6aadeb 100644 --- a/text/0416-glimmer-components.md +++ b/text/0416-glimmer-components.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-12-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/416 Tracking: https://github.com/emberjs/rfc-tracking/issues/2 diff --git a/text/0418-deprecate-route-render-methods.md b/text/0418-deprecate-route-render-methods.md index 9c1e22ebba..b1e2caa7de 100644 --- a/text/0418-deprecate-route-render-methods.md +++ b/text/0418-deprecate-route-render-methods.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-19-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/418 Tracking: https://github.com/emberjs/rfc-tracking/issues/30 diff --git a/text/0421-deprecate-application-controller-props.md b/text/0421-deprecate-application-controller-props.md index 15cff7c2f7..2fba5bcc25 100644 --- a/text/0421-deprecate-application-controller-props.md +++ b/text/0421-deprecate-application-controller-props.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-19-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/421 Tracking: https://github.com/emberjs/rfc-tracking/issues/5 @@ -8,7 +11,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/5 # Deprecate Application Controller Router Properties -## Summary +## Summary This RFC proposes the deprecation of `ApplicationController#currentPath` and `ApplicationController#currentRouteName`. diff --git a/text/0425-website-redesign.md b/text/0425-website-redesign.md index 0fea321c28..625eb90632 100644 --- a/text/0425-website-redesign.md +++ b/text/0425-website-redesign.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-12-21 +Release Date: FIXME +Release Versions: N/A Relevant Team(s): Learning, Steering RFC PR: https://github.com/emberjs/rfcs/pull/425 Tracking: https://github.com/emberjs/rfc-tracking/issues/35 diff --git a/text/0431-guides-restructure.md b/text/0431-guides-restructure.md index cff314aa17..ec11095fa0 100644 --- a/text/0431-guides-restructure.md +++ b/text/0431-guides-restructure.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2018-01-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Learning RFC PR: https://github.com/emberjs/rfcs/pull/431 Tracking: https://github.com/emberjs/rfc-tracking/issues/29 @@ -53,7 +56,7 @@ We are confident that this is possible thanks to the incredible response and eff There are many different types of documentation within Ember, so it's important to identify a target audience for each, in order to guide decision making and provide a learning flow that grows with the reader. -There are 3 main audiences for our resources: +There are 3 main audiences for our resources: 1. newcomers 2. upgraders @@ -95,7 +98,7 @@ The following Table of Contents will be applied iteratively over the course of m - Deploying - Upgrading (will contain links to upgrade resources, Editions, Deprecations) - Developer Tools (currently named Ember Inspector) -- Reference +- Reference - Accessibility - Syntax conversion guide diff --git a/text/0432-contextual-helpers.md b/text/0432-contextual-helpers.md index 282e807712..f335aef33b 100644 --- a/text/0432-contextual-helpers.md +++ b/text/0432-contextual-helpers.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2018-12-17 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/432 Tracking: https://github.com/emberjs/rfc-tracking/issues/6 diff --git a/text/0435-modifier-splattributes.md b/text/0435-modifier-splattributes.md index bfc50a5055..ff1a39a475 100644 --- a/text/0435-modifier-splattributes.md +++ b/text/0435-modifier-splattributes.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-01-18 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/435 Tracking: https://github.com/emberjs/rfc-tracking/issues/9 diff --git a/text/0440-decorator-support.md b/text/0440-decorator-support.md index 34e9574255..7c5766f484 100644 --- a/text/0440-decorator-support.md +++ b/text/0440-decorator-support.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-02-06 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/440 Tracking: https://github.com/emberjs/rfc-tracking/issues/41 diff --git a/text/0445-deprecate-with.md b/text/0445-deprecate-with.md index 68e6a0fae9..3add38d328 100644 --- a/text/0445-deprecate-with.md +++ b/text/0445-deprecate-with.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-02-13 +Release Date: FIXME +Release Versions: FIXME Relevant Teams: Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/445 Tracking: https://github.com/emberjs/rfc-tracking/issues/40 diff --git a/text/0446-contribution-guides.md b/text/0446-contribution-guides.md index 31a270199d..71e839d6aa 100644 --- a/text/0446-contribution-guides.md +++ b/text/0446-contribution-guides.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-02-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Learning RFC PR: https://github.com/emberjs/rfcs/pull/446 Tracking: https://github.com/emberjs/rfc-tracking/issues/39 diff --git a/text/0449-deprecate-partials.md b/text/0449-deprecate-partials.md index ada5516170..503ff18e90 100644 --- a/text/0449-deprecate-partials.md +++ b/text/0449-deprecate-partials.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-02-17 +Release Date: FIXME +Release Versions: FIXME Relevant Teams: Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/449 Tracking: https://github.com/emberjs/rfc-tracking/issues/38 @@ -14,7 +17,7 @@ Partials are an old Ember construct that have no benefits and many downsides whe ## Motivation -Partials have a number of downsides when compared with components: +Partials have a number of downsides when compared with components: - They are hard to reason about as they inherit the scope of the calling template - They perform poorly in comparison to components diff --git a/text/0451-injection-parameter-normalization.md b/text/0451-injection-parameter-normalization.md index 7cc16056a4..3fce8d3a1b 100644 --- a/text/0451-injection-parameter-normalization.md +++ b/text/0451-injection-parameter-normalization.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-02-19 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Ember Data, Learning RFC PR: https://github.com/emberjs/rfcs/pull/451 Tracking: https://github.com/emberjs/rfc-tracking/issues/34 diff --git a/text/0452-ember-data-medium-term-plan.md b/text/0452-ember-data-medium-term-plan.md index a51011489e..fa8e30097e 100644 --- a/text/0452-ember-data-medium-term-plan.md +++ b/text/0452-ember-data-medium-term-plan.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-02-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/452 Tracking: https://github.com/emberjs/rfc-tracking/issues/50 @@ -47,9 +51,9 @@ However, we will not succeed in delivering this future vision in a timely manner # Increasing velocity and stability -Ember Data has continuously evolved over seven years and over time acquired several layers of cruft along with a intimately connected internal architecture. The current state of the library is not particularly hospitable to new contributors while at the same time being hard to iterate on in a stable manner. Lots of Ember Data's public apis have been designed with stability and extensibility in mind, but the internal layers of the library have not benefited from the same amount of design work. The unspecified internal layers together with a host of implicit dependencies make it hard to expose parts of Ember Data to addon developers as well as prevent ED contributors from being able to easily do experimental iterative work. +Ember Data has continuously evolved over seven years and over time acquired several layers of cruft along with a intimately connected internal architecture. The current state of the library is not particularly hospitable to new contributors while at the same time being hard to iterate on in a stable manner. Lots of Ember Data's public apis have been designed with stability and extensibility in mind, but the internal layers of the library have not benefited from the same amount of design work. The unspecified internal layers together with a host of implicit dependencies make it hard to expose parts of Ember Data to addon developers as well as prevent ED contributors from being able to easily do experimental iterative work. -The three main problems this internal structure causes us is: +The three main problems this internal structure causes us is: - It is hard for developers to grok the codebase and become prolific contributors due to the complexity - Testing ideas in addons is usually a great way to move faster and derisk ideas. However due to the internal structure of ED, such addons use a large surface area of internal apis, negating most of the benefits @@ -79,7 +83,7 @@ Success criteria for this plan is shipping an Ember data release which: While the internal apis and interfaces will be designed with an eye towards the future public and addon use, in this phase of the work we will not be exposing all of them to apps and addons as fully stable public apis, or we will do so for addon author with an explicit plan to deprecate and replace. -Moreover, as part of the RFC we will not be deciding on, or baking in the future app level public apis. +Moreover, as part of the RFC we will not be deciding on, or baking in the future app level public apis. # High Level plan @@ -104,7 +108,7 @@ While the overall shape of the architecture looks as you might expect, our curre - Entire library implicitly relies on DS.Model classes, Ember's object model - The division of responsibilities between internalModel, RecordData, Store are not clear -This medium size ball of mud should be refactored to the following high level pieces: (add diagram here): +This medium size ball of mud should be refactored to the following high level pieces: (add diagram here): ![](https://i.imgur.com/C3tNcH2.png) @@ -119,7 +123,7 @@ This medium size ball of mud should be refactored to the following high level pi - Query builder - a service which takes user queries such as `findRecord` and turns them into Orbit.js like query objects that can be passed around - Fetching service - layer that takes user queries, relationship queries and save requests and decides whether they need fulfillment, and if so delegates to adapter/serialzier. Currently done by a mix of store and internal model. -Adapter, Serializer and Snapshots would not have major changes at this time, other than those needed to make use of the schema service and public apis for accessing records. +Adapter, Serializer and Snapshots would not have major changes at this time, other than those needed to make use of the schema service and public apis for accessing records. It is important to note that none of the existing public user apis would change, and that the bulk of this work is taking existing code structures and making the specified and isolated. diff --git a/text/0457-nested-lookups.md b/text/0457-nested-lookups.md index cb98885b11..8f70f7d477 100644 --- a/text/0457-nested-lookups.md +++ b/text/0457-nested-lookups.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-05 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/457 Tracking: https://github.com/emberjs/rfc-tracking/issues/37 diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md index f139b9b011..7d1af37cec 100644 --- a/text/0459-angle-bracket-built-in-components.md +++ b/text/0459-angle-bracket-built-in-components.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-05 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/459 Tracking: https://github.com/emberjs/rfc-tracking/issues/36 diff --git a/text/0460-yieldable-named-blocks.md b/text/0460-yieldable-named-blocks.md index 3ddd1fccfa..4efa3ec5bb 100644 --- a/text/0460-yieldable-named-blocks.md +++ b/text/0460-yieldable-named-blocks.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-06 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/460 diff --git a/text/0461-ember-data-singleton-record-data.md b/text/0461-ember-data-singleton-record-data.md index 14515ec9af..a5482a67c4 100644 --- a/text/0461-ember-data-singleton-record-data.md +++ b/text/0461-ember-data-singleton-record-data.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-03-06 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/461 Tracking: https://github.com/emberjs/rfc-tracking/issues/51 diff --git a/text/0463-record-data-state.md b/text/0463-record-data-state.md index bd652fe330..58086e36dc 100644 --- a/text/0463-record-data-state.md +++ b/text/0463-record-data-state.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-03-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): data RFC PR: https://github.com/emberjs/rfcs/pull/463 Tracking: https://github.com/emberjs/rfc-tracking/issues/47 @@ -7,7 +11,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/47 --- # Record State on Record Data RFC - + ## Summary @@ -23,16 +27,16 @@ RecordData handles managing local and server state for records. While the curren Add the following methods on the RecordData interface: -```ts +```ts interface RecordData { - + // To be added in this RFC isNew(identifier: RecordIdentifier): boolean isDeleted(identifier: RecordIdentifier): boolean isDeletionCommitted(identifier: RecordIdentifier): boolean - + setIsDeleted(identifier: RecordIdentifier, boolean: isDeleted): void } ``` @@ -73,14 +77,14 @@ export interface RecordDataStoreWrapper { } ``` -Currently calling `rollbackAttributes` rolls back `isDeleted` to a non deleted state. This logic would be the responsibility of Record Data to implement. +Currently calling `rollbackAttributes` rolls back `isDeleted` to a non deleted state. This logic would be the responsibility of Record Data to implement. ## How we teach this -We currently do not have a comprehensive way to teach RecordData api. This RFC will be tought alongisde the rest of upcoming Record Data docs. +We currently do not have a comprehensive way to teach RecordData api. This RFC will be tought alongisde the rest of upcoming Record Data docs. ## Alternatives -Instead of separate methods, have a single methods, somehting like `getState` that returns a POJO with keys like +Instead of separate methods, have a single methods, somehting like `getState` that returns a POJO with keys like { isDeleted: true, isNew: false } diff --git a/text/0465-record-data-errors.md b/text/0465-record-data-errors.md index 43068f9a8f..116d8736df 100644 --- a/text/0465-record-data-errors.md +++ b/text/0465-record-data-errors.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-03-13 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): data RFC PR: https://github.com/emberjs/rfcs/pull/465 Tracking: https://github.com/emberjs/rfc-tracking/issues/46 @@ -25,7 +29,7 @@ When a user sends a record save request, it can fail in two different ways: ## Detailed design -Currently on a failed save, Record Data receives a call to +Currently on a failed save, Record Data receives a call to `commitWasRejected(recordIdentifier: RecordIdentifier): void;` @@ -46,7 +50,7 @@ interface RecordData { } ``` -`RecordValidationError` follows the subset of the JSON api errors spec. For example, if the record being saved was rejected because the attribute `password` was empty, the `RecordValidationError` could look like: +`RecordValidationError` follows the subset of the JSON api errors spec. For example, if the record being saved was rejected because the attribute `password` was empty, the `RecordValidationError` could look like: ```ts { @@ -58,7 +62,7 @@ interface RecordData { } ``` -The source pointer is a JSON pointer relative to the Resource Object. +The source pointer is a JSON pointer relative to the Resource Object. We would also add a method on the `RecordDataStoreWrapper` to enable Record Data to notify the store that the errors properties have changed. ```ts @@ -71,7 +75,7 @@ There would be no api for changing the errors from the client side, they would b ## How we teach this -We currently do not have a comprehensive way to teach the RecordData api. This RFC will be taught alongisde the rest of upcoming Record Data docs. +We currently do not have a comprehensive way to teach the RecordData api. This RFC will be taught alongisde the rest of upcoming Record Data docs. ## Alternatives diff --git a/text/0466-request-state-service.md b/text/0466-request-state-service.md index 5a43e45183..5c0a9d73cb 100644 --- a/text/0466-request-state-service.md +++ b/text/0466-request-state-service.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be at a further stage. +Stage: Accepted Start Date: 2019-03-09 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): data RFC PR: https://github.com/emberjs/rfcs/pull/466 Tracking: https://github.com/emberjs/rfc-tracking/issues/52 @@ -7,7 +11,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/52 --- # Request State Service - + ## Summary @@ -87,7 +91,7 @@ Expose a service on the store ```ts class Store { getRequestStateService(): RequestStateService -} +} ``` Using these we can reimplement the current `isSaving` method on `DS.Model` diff --git a/text/0468-classic-decorator.md b/text/0468-classic-decorator.md index 28e681bd88..c016339ca6 100644 --- a/text/0468-classic-decorator.md +++ b/text/0468-classic-decorator.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Ember Data, Learning RFC PR: https://github.com/emberjs/rfcs/pull/468 Tracking: https://github.com/emberjs/rfc-tracking/issues/55 diff --git a/text/0470-fn-helper.md b/text/0470-fn-helper.md index 3deeb69ada..7e75cfcc96 100644 --- a/text/0470-fn-helper.md +++ b/text/0470-fn-helper.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/470 Tracking: https://github.com/emberjs/rfc-tracking/issues/33 diff --git a/text/0471-on-modifier.md b/text/0471-on-modifier.md index 7cc2039706..e169f34c23 100644 --- a/text/0471-on-modifier.md +++ b/text/0471-on-modifier.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-03-21 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/471 Tracking: https://github.com/emberjs/rfc-tracking/issues/32 diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 390eafd5f3..f26afbd5e5 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be at a further stage +Stage: Accepted Start Date: 2019-04-17 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/477 diff --git a/text/0478-tracked-properties-updates.md b/text/0478-tracked-properties-updates.md index ac04e66384..29d57a19f0 100644 --- a/text/0478-tracked-properties-updates.md +++ b/text/0478-tracked-properties-updates.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-04-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/478 Tracking: https://github.com/emberjs/rfc-tracking/issues/45 diff --git a/text/0481-component-templates-co-location.md b/text/0481-component-templates-co-location.md index a3e469d52d..2ae63aa89e 100644 --- a/text/0481-component-templates-co-location.md +++ b/text/0481-component-templates-co-location.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-04-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/481 diff --git a/text/0486-deprecate-mouseenter.md b/text/0486-deprecate-mouseenter.md index 02e4e3519b..f378801d98 100644 --- a/text/0486-deprecate-mouseenter.md +++ b/text/0486-deprecate-mouseenter.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-04-28 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/486 Tracking: https://github.com/emberjs/rfc-tracking/issues/54 @@ -11,47 +14,47 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/54 ## Summary Deprecate support for `mouseenter`, `mouseleave` and `mousemove` events in Ember's EventDispatcher. This affects -the corresponding event handler methods (`mouseEnter() {}`) in Ember components and -`{{action "some" on="mouseenter"}}`. +the corresponding event handler methods (`mouseEnter() {}`) in Ember components and +`{{action "some" on="mouseenter"}}`. ## Motivation Ember's EventDispatcher handles "Ember events" by attaching listeners to the app's root element -and relying on the events bubbling up to that element (aka event delegation). There they -are processed and invoke any matching `Ember.Component` event handler method with -the same (camel-cased) method as the event type. Same for element-space `{{action}}` +and relying on the events bubbling up to that element (aka event delegation). There they +are processed and invoke any matching `Ember.Component` event handler method with +the same (camel-cased) method as the event type. Same for element-space `{{action}}` modifiers. -> Note: for a "Deep Dive on Ember Events" and how they differ from "native events" I refer to -Marie Chatfield's excellent +> Note: for a "Deep Dive on Ember Events" and how they differ from "native events" I refer to +Marie Chatfield's excellent [blog post](https://medium.com/square-corner-blog/deep-dive-on-ember-events-cf684fd3b808) or [EmberConf talk](https://youtu.be/G9hXjjHFJVs) This works fine in general, but `mouseenter`/`mouseleave` events are special as they do not bubble. In the past it still worked nevertheless as jQuery transparently handled this -for us, as it had special support for event delegation for these events, essentially by using +for us, as it had special support for event delegation for these events, essentially by using (bubbling) `mouseover` events to replicate the semantics of `mouseenter`/`mouseleave` events. When support for jQuery-less apps was introduced, this [left a hole](https://github.com/emberjs/ember.js/issues/16591) in the jQuery-less EventDispatcher implementation. But as support for those events was and still is part of Ember's pubic API, we had no chance other than to [implement support -for jQuery-less apps](https://github.com/emberjs/ember.js/pull/16603) using the same +for jQuery-less apps](https://github.com/emberjs/ember.js/pull/16603) using the same `mouseover` based approach. This however comes with a cost: besides an [unresolved issue](https://github.com/emberjs/ember.js/issues/17228) -the implementation has some performance drawbacks, as it has to process every `mouseover` event on -*any* element, create fake `mouseenter`/`mouseleave` events and try to dispatch them, even when -not a single component/action needs them. +the implementation has some performance drawbacks, as it has to process every `mouseover` event on +*any* element, create fake `mouseenter`/`mouseleave` events and try to dispatch them, even when +not a single component/action needs them. -Deprecating support for `mousemove` is also proposed, which is a (bubbling) event that does not have the higher +Deprecating support for `mousemove` is also proposed, which is a (bubbling) event that does not have the higher implementation cost as `mouseenter`/`mouseleave`, but nevertheless requires the EventDispatcher to optimistically handle these extremely high-volume events. -While efforts to make this more "pay as you go" are [possible](https://github.com/emberjs/ember.js/pull/17911), +While efforts to make this more "pay as you go" are [possible](https://github.com/emberjs/ember.js/pull/17911), the trade-off of keeping support around still seems unfavorable, as these events fire so frequently, while they are (most certainly) very rarely used. -This is even more so given that Glimmer Components with their outerHTML semantics do not +This is even more so given that Glimmer Components with their outerHTML semantics do not work with event handler methods, and `{{action}}` will eventually fade away in favor of `{{on}}` using native `addListener()`. @@ -86,12 +89,12 @@ export default class MyComponent extends Component { handleMouseEnter(e) { // do something } - + didInsertElement() { super.didInsertElement(...arguments); this.element.addEventListener('mouseenter', this.handleMouseEnter); } - + willDestroyElement() { super.willDestroyElement(...arguments); this.element.removeEventListener('mouseenter', this.handleMouseEnter); @@ -108,7 +111,7 @@ import { action } from '@ember/object'; export default class MyComponent extends Component { tagName = ''; - + @action handleMouseEnter(e) { // do something @@ -143,8 +146,8 @@ After (based on [RFC471](https://github.com/emberjs/rfcs/blob/master/text/0471-o The deprecation guide should explain the transition path as shown above. -The references to `mouseenter`, `mouseleave` and `mousemove` should be removed from the Guide's -[Handling Events](https://guides.emberjs.com/release/components/handling-events/#toc_event-names) section and the API +The references to `mouseenter`, `mouseleave` and `mousemove` should be removed from the Guide's +[Handling Events](https://guides.emberjs.com/release/components/handling-events/#toc_event-names) section and the API docs for [Components events](https://api.emberjs.com/ember/release/classes/Component). Other than that, no changes are required, as the replacement APIs are all available and @@ -160,7 +163,7 @@ should not be a major issue. ## Alternatives -We could keep support in place, and eventually work on optimizations that minimize the +We could keep support in place, and eventually work on optimizations that minimize the performance impact. ## Unresolved questions diff --git a/text/0487-custom-model-classes.md b/text/0487-custom-model-classes.md index cb61535354..6d5c6015ce 100644 --- a/text/0487-custom-model-classes.md +++ b/text/0487-custom-model-classes.md @@ -1,5 +1,9 @@ --- +# FIXME: This may actually be a further stage +Stage: Accepted Start Date: 2019-05-09 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): data RFC PR: https://github.com/emberjs/rfcs/pull/487 Tracking: https://github.com/emberjs/rfc-tracking/issues/53 @@ -12,7 +16,7 @@ Tracking: https://github.com/emberjs/rfc-tracking/issues/53 This RFC is a follow-up RFC for #293 RecordData and replaces [https://github.com/runspired/rfcs/blob/ember-data-custom-records/text/0000-ember-data-model-factory-for.md#ember-data--modelfactoryfor](https://github.com/runspired/rfcs/blob/ember-data-custom-records/text/0000-ember-data-model-factory-for.md#ember-data--modelfactoryfor) -Create a way for addons and user to define their own implementation of a model class. Adds an `instantiateRecord` method to `Store` which would allow addons and ED itself to offer a clean replacement the default DS.Model with a custom Model class. +Create a way for addons and user to define their own implementation of a model class. Adds an `instantiateRecord` method to `Store` which would allow addons and ED itself to offer a clean replacement the default DS.Model with a custom Model class. ## Motivation @@ -29,9 +33,9 @@ This RFC represents the first step in separating the record implementation from ## Detailed design -After the work in [Record Data Errors RFC](https://github.com/emberjs/rfcs/pull/465), [Record Data State RFC](https://github.com/emberjs/rfcs/pull/463), and [Request State Service RFC](https://github.com/emberjs/rfcs/pull/466) we have enough coverage in public apis that we can implement the entire DS.Model class with just a few changes to Store APIs. +After the work in [Record Data Errors RFC](https://github.com/emberjs/rfcs/pull/465), [Record Data State RFC](https://github.com/emberjs/rfcs/pull/463), and [Request State Service RFC](https://github.com/emberjs/rfcs/pull/466) we have enough coverage in public apis that we can implement the entire DS.Model class with just a few changes to Store APIs. -We will need five separate changes: +We will need five separate changes: - A way to instantiate custom Records and for them to be able to access underlying record data - A way for those records to be notified of changes in Record Data @@ -53,18 +57,18 @@ The following interface shows the interface of these methods: interface RecordDataWrapper { // proxies a subset of RD methods and hides the rest getAttr(identifier: RecordIdentifier, key: string) isAttrDirty(identifier: RecordIdentifier, key) - + changedAttributes(identifier: RecordIdentifier) hasChangedAttributes(identifier: RecordIdentifier) rollbackAttributes(identifier: RecordIdentifier) - + getRelationship(identifier: RecordIdentifier, key: string) - + setRecordId(identifier: RecordIdentifier, id: string): void; - + getErrors(identifier: RecordIdentifier) getMeta(identifier: RecordIdentifier) - + isNew(identifier: RecordIdentifier): boolean; isDeleted(identifier: RecordIdentifier): boolean; @@ -76,31 +80,31 @@ interface RecordDataWrapper { // proxies a subset of RD methods and hides the re setDirtyBelongsTo(name: string, identifier: Identifier | null): void; } - + interface RecordDataFor { (identifier: RecordIdentifier): RecordDataWrapper } - + class Store { instantiateRecord( - identifier: RecordIdentifier, + identifier: RecordIdentifier, createRecordArgs: { [key: string]: any }, // args passed in to store.createRecord() and processed by recordData to be set on creation - recordDataFor: RecordDataFor, + recordDataFor: RecordDataFor, notificationManager: NotificationManager): unknown - + teardownRecord(record): void } ``` Instead of passing the entire RecordData Class to `instantiateRecord`, we pass in a lookup method that returns a record data wrapper which exposes only the local facing methods and hide the server/adapter facing methods that the Model should not have access to. -We also expose `teardownRecord`, which will get called whenever a record is getting unloaded, or otherwise disposed of (if we add future ways of destroying records that are uncoupled from unloading) from the identity map, thus giving addons an opportunity to perform cleanup. +We also expose `teardownRecord`, which will get called whenever a record is getting unloaded, or otherwise disposed of (if we add future ways of destroying records that are uncoupled from unloading) from the identity map, thus giving addons an opportunity to perform cleanup. ## Change Notification In order for the record class to learn about changes to the underlying data, it will be passed a `NotificationManager` as a constructor argument, which will allow it to -subscribe and unsubscribe to notifications of underlying changes to the data. Once `RecordData` calls one of the notification methods, the notification manager will call -any registered callback for the given identifier, and pass in the type of the notification, allowing the record the opportunity to repull the data if needed. There are no guarantees around the timing of the notification callback being called after `RecordData` informs the store of changes. We expect that in a modern Ember app with tracked properties, this wouldn't be the common path for tracking changes. +subscribe and unsubscribe to notifications of underlying changes to the data. Once `RecordData` calls one of the notification methods, the notification manager will call +any registered callback for the given identifier, and pass in the type of the notification, allowing the record the opportunity to repull the data if needed. There are no guarantees around the timing of the notification callback being called after `RecordData` informs the store of changes. We expect that in a modern Ember app with tracked properties, this wouldn't be the common path for tracking changes. ```ts function unsubscribe(token: UnsubscribeToken) @@ -108,7 +112,7 @@ function unsubscribe(token: UnsubscribeToken) interface NotificationCallback { (identifier: Identifier, notificationType: 'attributes' | 'relationships' | 'errors' | 'meta' | 'unload'): void; } - + interface NotificationManager { subscribe(identifier, NotificationCallback): UnsubscribeToken } @@ -117,7 +121,7 @@ interface NotificationManager { ## Exposing schema information We currently keep schema information on `DS.Model` class. In order to allow for custom Model implementations we need to allow lookup of schema info from the store. We already have specified a schema api that RecordData consumes: `attributesDefinitionFor` and `relationshipDefinitionFor`. We would define on a schema interface that the store would expose and addons could use. **The schema methods are not ergonomic on purpose.** They match the current Record Data apis and are designed as a stepping stone on the way of having a better, user facing schema APIs. Addons could provide their own `SchemaDefinitionService` by calling `registerSchemaDefinitionService`. We would initially not allow calling `registerSchemaDefinitionService` more than once, but this constraint could potentially be relaxed in the future. The schema info is currently primarily geared towards being used by the internal relationship handling layer, the serializer/adapter layers and the DebugAdapter. Schema methods support both static and dynamic schema computation. For static schemas, the method can always respond with a schema definition based on the type passed, and for dynamic changing schemas, it can look up the underlying data by the identifer which is passed in. We would also add a method called `doesTypeExist`, which would return `true` if ED knew that a given string is a model type and `false` otherwise. - + ```ts export interface RelationshipDefinition { @@ -126,11 +130,11 @@ export interface RelationshipDefinition { options: { [key: string]: any } ; name: string; } - + interface RelationshipsDefinition { [key: string]: RelationshipDefinition } - + interface AttributeDefinition { name: string; options: { [key: string]: any }; @@ -140,11 +144,11 @@ interface AttributeDefinition { interface AttributesDefinition { [key: string]: AttributeDefinition } - + interface SchemaDefinitionService { - // Following the existing RD implementation + // Following the existing RD implementation attributesDefinitonFor(identifier: RecordIdentifier | type: string): AttributesDefiniton - + // Following the existing RD implementation relationshipsDefinitionFor(identifier: RecordIdentifier | type: string): RelationshipsDefinition @@ -158,7 +162,7 @@ class Store { } ``` -## Adding store methods for manipulating records +## Adding store methods for manipulating records Currently there exist methods on DS.Model that call into `internalModel` for it's functionality. In order for a parallel implementation to be possible, we need to expose that functionality through public methods on the store. @@ -171,7 +175,7 @@ class Store { } ``` -this would allow you to have a custom model class like this: +this would allow you to have a custom model class like this: ```ts class CustomModel { @@ -183,7 +187,7 @@ class CustomModel { ### Record Arrays -Currently Ember Data manages live Record Arrays which are returned as a response to query methods such as `findAll` or `queryRecords`. Because ED can track records which are returned from `instantiateRecord`, it will be able to seamlessly manage custom models which are part of Ember Data record arrays and clean them up correctly. +Currently Ember Data manages live Record Arrays which are returned as a response to query methods such as `findAll` or `queryRecords`. Because ED can track records which are returned from `instantiateRecord`, it will be able to seamlessly manage custom models which are part of Ember Data record arrays and clean them up correctly. If an addon implements it's own record array like structures, it will be able to manage membership of Ember Data default records by subclassing `teardownRecord`, which gives it a convinient place to listen for a record being destroyed. @@ -208,7 +212,7 @@ modelFor(modelName) When serializing we already have a `Snapshot` passed in as an argument which has all of the information that a `ModelClass` provides. We would deprecate the class argument being passed in, and instruct the user to refactor towards using the `Snapshot`. -For example: +For example: ```ts createRecord(store, type, snapshot) { let url = `/api/${type.modelName}`; @@ -230,7 +234,7 @@ createRecord(store, type, snapshot) { While `Snapshot` roughly corresponds to a `Request` like object to be used while serializing, and we intend to in the future refactor it to be a request object, we don't have a similar construct when normalizing. In the future, normalizing will have a corresponding `Response` like object exposed, but for the time being we can still deprecate using the `primaryModelClass` argument for anything other than `modelName`, `eachAttribute`, `eachRelationship`. If a user accesses any other property on the `primaryModelClass` they will receive a deprecation. If there was a custom model instance provided, and we had no corresponding class to pass in to `normalizeResponse` we would pass in a shim class that only exposed the `modelName` property, and `eachAttribute` and `eachRelationship` methods which would proxy to the underlying schema methods, thus allowing the normalization layers to continue working with custom model classes. - + ```ts interface ClassSchemaShim { modelName: string; diff --git a/text/0491-deprecate-disconnect-outlet.md b/text/0491-deprecate-disconnect-outlet.md index 62bfa8a84c..93ff753f85 100644 --- a/text/0491-deprecate-disconnect-outlet.md +++ b/text/0491-deprecate-disconnect-outlet.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-05-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/491 diff --git a/text/0494-async-observers.md b/text/0494-async-observers.md index 689235cc4c..d1b47c63d5 100644 --- a/text/0494-async-observers.md +++ b/text/0494-async-observers.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-05-30 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/494 diff --git a/text/0496-handlebars-strict-mode.md b/text/0496-handlebars-strict-mode.md index 1d959d7ae2..4dc025526b 100644 --- a/text/0496-handlebars-strict-mode.md +++ b/text/0496-handlebars-strict-mode.md @@ -1,5 +1,8 @@ --- +Stage: Accepted Start Date: 2019-02-14 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/496 diff --git a/text/0507-embroider-v2-package-format.md b/text/0507-embroider-v2-package-format.md index 94ef3057c4..05b76e7d20 100644 --- a/text/0507-embroider-v2-package-format.md +++ b/text/0507-embroider-v2-package-format.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-06-21 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI, Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/507 diff --git a/text/0519-2019-2020-roadmap.md b/text/0519-2019-2020-roadmap.md index f8514601e4..d317ef8853 100644 --- a/text/0519-2019-2020-roadmap.md +++ b/text/0519-2019-2020-roadmap.md @@ -1,6 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-07-29 Heavily Revised: 2020-02-28 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): All teams RFC PR: https://github.com/emberjs/rfcs/pull/519 diff --git a/text/0521-find-by-identifier.md b/text/0521-find-by-identifier.md index 67a2603eeb..4ed85d0e13 100644 --- a/text/0521-find-by-identifier.md +++ b/text/0521-find-by-identifier.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-08-29 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): EmberData RFC PR: https://github.com/emberjs/rfcs/pull/521 diff --git a/text/0522-default-serializers-and-adapters.md b/text/0522-default-serializers-and-adapters.md index 0bb8336bfe..a07d95c13e 100644 --- a/text/0522-default-serializers-and-adapters.md +++ b/text/0522-default-serializers-and-adapters.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2019-07-27 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/522 diff --git a/text/0523-model-argument-for-route-templates.md b/text/0523-model-argument-for-route-templates.md index 6d6524e636..3fb79664d0 100644 --- a/text/0523-model-argument-for-route-templates.md +++ b/text/0523-model-argument-for-route-templates.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-08-05 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/523 diff --git a/text/0554-deprecate-getwithdefault.md b/text/0554-deprecate-getwithdefault.md index dd16d668d2..c05d440eb3 100644 --- a/text/0554-deprecate-getwithdefault.md +++ b/text/0554-deprecate-getwithdefault.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2019-11-08 +Release Date: FIXME +Release Versions: + ember-source: v3.21.0 Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/554 @@ -19,7 +23,7 @@ Given the JavaScript language will soon (currently in Stage 3) give us the appro ## Transition Path -Ember will start logging deprecation messages for `getWithDefault` usage. +Ember will start logging deprecation messages for `getWithDefault` usage. We can codemod our current usage of `getWithDefault` with the equivalent behaviour using plain JavaScript. The migration guide will cover this example: @@ -119,7 +123,7 @@ let { falseValue = defaultValue } = obj; Add the transition path to the [Ember Deprecation Guide](https://deprecations.emberjs.com/). -The references to `getWithDefault` will need to be removed from the [API docs](https://api.emberjs.com/ember/release/functions/@ember%2Fobject/getWithDefault). +The references to `getWithDefault` will need to be removed from the [API docs](https://api.emberjs.com/ember/release/functions/@ember%2Fobject/getWithDefault). There are no changes needed for the [Ember Guides](https://guides.emberjs.com/release/) since we do not use it anywhere. diff --git a/text/0558-edition-detection.md b/text/0558-edition-detection.md index 3203ea3d75..951847a726 100644 --- a/text/0558-edition-detection.md +++ b/text/0558-edition-detection.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2019-11-20 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Ember CLI, Ember Data RFC PR: https://github.com/emberjs/rfcs/pull/558 diff --git a/text/0560-add-equality-operators.md b/text/0560-add-equality-operators.md index 8e82ea807e..83f0abf1f8 100644 --- a/text/0560-add-equality-operators.md +++ b/text/0560-add-equality-operators.md @@ -1,7 +1,13 @@ -- Start Date: 2019-12-08 -- Relevant Team(s): (fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies) -- RFC PR: https://github.com/emberjs/rfcs/pull/560 -- Tracking: (leave this empty) +--- +Stage: Accepted +Start Date: 2019-12-08 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: https://github.com/emberjs/rfcs/pull/560 +--- # Adding Equality Operators to Templates diff --git a/text/0562-add-logical-operators.md b/text/0562-add-logical-operators.md index 36091c5bb4..0afc319845 100644 --- a/text/0562-add-logical-operators.md +++ b/text/0562-add-logical-operators.md @@ -3,8 +3,8 @@ Stage: Accepted Start Date: 2019-12-08 Release Date: Unreleased Release Versions: -ember-source: vX.Y.Z -ember-data: vX.Y.Z + ember-source: vX.Y.Z + ember-data: vX.Y.Z Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/562 --- diff --git a/text/0566-memo-decorator.md b/text/0566-memo-decorator.md index a1955533ba..dc5b1391ea 100644 --- a/text/0566-memo-decorator.md +++ b/text/0566-memo-decorator.md @@ -1,4 +1,5 @@ --- +# FIXME: This may be a further stage Stage: Accepted Start Date: 2019-12-22 Release Date: Unreleased diff --git a/text/0580-destroyables.md b/text/0580-destroyables.md index 7548fb8516..9633831fc7 100644 --- a/text/0580-destroyables.md +++ b/text/0580-destroyables.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-01-10 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/580 diff --git a/text/0581-new-test-waiters.md b/text/0581-new-test-waiters.md index bd3e71cf5e..fd2ea6eb96 100644 --- a/text/0581-new-test-waiters.md +++ b/text/0581-new-test-waiters.md @@ -1,5 +1,10 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-01-14 +Release Date: FIXME +Release Versions: FIXME +Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/581 --- diff --git a/text/0585-improved-ember-registry-apis.md b/text/0585-improved-ember-registry-apis.md index f678ea8d37..ad4377183b 100644 --- a/text/0585-improved-ember-registry-apis.md +++ b/text/0585-improved-ember-registry-apis.md @@ -1,5 +1,10 @@ --- +Stage: Accepted Start Date: 2020-01-27 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z Relevant Team(s): Ember.js, Learning RFC PR: https://github.com/emberjs/rfcs/pull/585 @@ -172,7 +177,7 @@ Besides the recent use of capabilities in the modifier and component managers, t ### Owner APIs -The owner APIs all change to use `Identifier` (or `FactoryTypeIdentifier` as appropriate) instead of strings. +The owner APIs all change to use `Identifier` (or `FactoryTypeIdentifier` as appropriate) instead of strings. Throughout, for the purposes of registration lookup, we use deep object value equality, *not* object identity. This specifically applies to: @@ -209,7 +214,7 @@ Some APIs refer to *factories* and *factory managers*. The API for these classes interface FactoryClass { positionalParams?: string | string[] | undefined | null; } - + interface Factory { class?: C; - fullName?: string; // DEPRECATED @@ -217,7 +222,7 @@ Some APIs refer to *factories* and *factory managers*. The API for these classes + identifier: FactoryIdentifier; create(props?: { [prop: string]: any }): T; } - + interface FactoryManager { readonly class: Factory; - readonly fullName?: string; // DEPRECATED @@ -305,13 +310,13 @@ The `'@'` form is deprecated and will be removed at 4.0. The no export default class Example { @service foo; - + @service('bar') barRenamed; - + @service({ name: 'quux' }) quuxViaIdentifier; - + @service({ namespace: 'baz', name: 'neato' }) neatoNamespaced; } @@ -357,11 +362,11 @@ The majority of uses are likely to be codemoddable, but not *all* will. > #### Deprecate registry string-based microsyntax > ##### until: 4.0.0 > ##### id: ember-resolver.string-based-microsyntax -> +> > Ember has historically supported a string-based microsyntax of the format `'@:'` (where both `@` and `:` are optional) for registering, resolving, looking up, and injecting items into Ember’s dependency injection container. These have been replaced with an object-based API where each part of the registry identifier is named explicitly. -> +> > You should replace calls using the string-based microsyntax with the new API. For example, these lookups in a test context: -> +> > ```js > this.owner.lookup('service:session'); > this.owner.register( @@ -374,7 +379,7 @@ The majority of uses are likely to be codemoddable, but not *all* will. > ``` > > Should be changed to: -> +> > ```js > this.owner.lookup({ type: 'service', name: 'session' }); > this.owner.register( @@ -522,7 +527,7 @@ Another brief syntax might use the type as the key and the name as its value: lookup({ service: 'foo' }) ``` -While this initially seems nice from the perspective of the consumer of the API, it muddies the API substantially and makes the implementation worse as well. +While this initially seems nice from the perspective of the consumer of the API, it muddies the API substantially and makes the implementation worse as well. On the API front, for example, what would this mean? @@ -579,7 +584,7 @@ export default class Session extends Service { login(email: string, password: string) { // ... } - + logout() { // ... } @@ -607,23 +612,23 @@ The Typed Ember blueprints generate that boilerplate for users, which (hopefully ```diff import Service from '@ember/service'; - + export default class Session extends Service { login(email: string, password: string) { // ... } - + logout() { // ... } } - + declare module '@ember/service' { interface Registry { session: Session; } } - + + declare module 'TBD-some-registry-spot' { + interface Registry { + 'service:session': typeof Session; diff --git a/text/0615-autotracking-memoization.md b/text/0615-autotracking-memoization.md index aeaa8164e4..07b0cba992 100644 --- a/text/0615-autotracking-memoization.md +++ b/text/0615-autotracking-memoization.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-04-17 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/615 diff --git a/text/0617-rfc-stages.md b/text/0617-rfc-stages.md index cfab788e69..5d09287a0f 100644 --- a/text/0617-rfc-stages.md +++ b/text/0617-rfc-stages.md @@ -1,5 +1,8 @@ --- +Stage: Accepted Start Date: 2020-04-22 +Release Date: Unreleased +Release Versions: N/A Relevant Team(s): All teams RFC PR: https://github.com/emberjs/rfcs/pull/617 @@ -52,9 +55,9 @@ There are two additional statuses for RFCs that will not move forward: #### Proposed -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. -There is currently a default template and a deprecation RFC template. This +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. +There is currently a default template and a deprecation RFC template. This process is discussed in depth in the RFCs repo README. An RFC's number is the number of it's original proposal PR. @@ -67,102 +70,102 @@ team(s) without an FCP. See [Exploring](#Exploring). #### 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 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 +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](#Accepted) +An Exploring RFC that is successfully completed can move to [Accepted](#Accepted) with an FCP is required as in the existing process. #### Accepted 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. +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. This is equivalent to today's RFCs being merged. -If there are unanswered questions, we have outlined them and expect that they +If there are unanswered questions, we have outlined them and expect that they will be answered before [Ready for Release](#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](#Ready-for-Release). This PR should be used to track + +When an RFC is merged and moved to "Accepted", a new PR will be opened to move +it to [Ready for Release](#Ready-for-Release). This PR should be used to track the implementation progress and gain consensus to move to that next stage. #### Ready for Release -The implementation is complete according to plan outlined in the RFC, +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. +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 +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. +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](#Recommended) after being [Released](#Released). +This stage should include a list of criteria for determining when the proposal +can be considered [Recommended](#Recommended) after being [Released](#Released). -A PR is opened on the repo (see [Accepted](#Accepted)) to move an accepted RFC +A PR is opened on the repo (see [Accepted](#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 +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. #### Released -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, +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, +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. +Ember's RFC process can be used for process and work plans that are not about code. Some examples include Roadmap RFCs, this RFC 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, +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 +An RFC is moved into "Released" when the above is verified by consensus of the relevant team(s) via PR to update the stage. #### Recommended -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 +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 +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: - 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 of +API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature. - If the proposal replaces an existing feature, the addon ecosystem has largely -updated to work with both old and new features. -- If the proposal updates or replaces an existing feature, high-quality codemods are +updated to work with both old and new features. +- If the proposal updates or replaces an existing feature, high-quality codemods are available - If needed, Ember debugging tools as well as popular IDE support have been updated to support the feature. - If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended". -- Any criteria for "Recommended" for this proposal that were established in the +- Any criteria for "Recommended" for this proposal that were established in the [Ready For Release](#Ready-for-Release) stage have been met. An RFC is moved into "Recommended" via PR to update the stage. An FCP is required @@ -171,14 +174,14 @@ the same PR. #### Closed -A [Proposed](#Proposed) RFC may be closed after an FCP period. This is the same +A [Proposed](#Proposed) RFC may be closed after an FCP period. This is the same as the existing process. A closed RFC is discontinued. #### Discontinued An previously [Accepted](#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. +may be superseded, out-of-date, or no longer consistent with the direction of +Ember. ### Editing merged RFCs @@ -191,7 +194,7 @@ A merged RFC may be edited via a Pull Request process. Edits may include things Today, these types of changes do happen. We just don't write them down. So, merge criteria should be very loose. -Major changes should have a new RFC. The old RFC is later marked "Discontinued" when the replacement is merged. +Major changes should have a new RFC. The old RFC is later marked "Discontinued" when the replacement is merged. ### Changes to RFC meta @@ -211,16 +214,16 @@ After: - Release date: Unreleased (later update with YYYY-MM-DD) - Release Versions: (Include any package with work necessary for the feature, n/a for non-code RFCs) - ember-source: vX.Y.Z - - ember-data: vX.Y.Z + - ember-data: vX.Y.Z - Relevant Team(s): (fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies) - RFC PR: (after opening the Propsoal RFC PR, update this with a link to it and update the file name) - -For RFCs that have moved through to at least the [Accepted](#Accepted) stage, + +For RFCs that have moved through to at least the [Accepted](#Accepted) stage, this data will be used to add and update a block at the top of the RFC prose to -indicate the current stage, with a brief explanation of that stage. It should -link to any open PRs to update the stage of the RFC. +indicate the current stage, with a brief explanation of that stage. It should +link to any open PRs to update the stage of the RFC. -We will make use of automation to add/update a section to the RFC with links to +We will make use of automation to add/update a section to the RFC with links to each PR that caused the RFC to move to a new stage. `Tracking` will be removed for new RFCs. Links that would have appeared here should @@ -234,13 +237,13 @@ A stage will be applied to all previously merged RFCs. ### Non-code RFCs -The names of the stages make the most sense with RFCs that propose features in -Ember, with code that will follow a release process. For many non-code RFCs, -such as this one, those names, especially of later stages, may seem "off". -However, it is still valuable to have a stage for every RFC where the teams and -community agree that the RFC has been implemented ([Ready for Release](#Ready-for-Release)) and a +The names of the stages make the most sense with RFCs that propose features in +Ember, with code that will follow a release process. For many non-code RFCs, +such as this one, those names, especially of later stages, may seem "off". +However, it is still valuable to have a stage for every RFC where the teams and +community agree that the RFC has been implemented ([Ready for Release](#Ready-for-Release)) and a stage where the community agree that the RFC has been polished ([Recommended](#Recommended)). -We may further refine this in a future RFC as we learn more. +We may further refine this in a future RFC as we learn more. ## How we teach this @@ -269,41 +272,41 @@ Here is how we could have applied this model to Tracked Properties, which was sp ### 0 - Proposed -A PR is opened to the RFCs repo for Tracked Properties. The framework team talks -about the RFC in the weekly meetings, and there's general agreement to pursue the -idea. The RFC moves to [Exploring](#Exploring). A label is added to the PR to +A PR is opened to the RFCs repo for Tracked Properties. The framework team talks +about the RFC in the weekly meetings, and there's general agreement to pursue the +idea. The RFC moves to [Exploring](#Exploring). A label is added to the PR to indicate that stage. ### 1 - Exploring -@pzuraq keeps adding details to the RFC, explores the design space, and -collaborates with others to get to the final design. The full story has been -thought out. @pzuraq expects to have the time resources to work on implementation. -There were no "known unknowns" questions. The RFC reaches consensus. The RFC -makes it through a week-long FCP process. The PR is merged and the stage -is now [Accepted](#Accepted). +@pzuraq keeps adding details to the RFC, explores the design space, and +collaborates with others to get to the final design. The full story has been +thought out. @pzuraq expects to have the time resources to work on implementation. +There were no "known unknowns" questions. The RFC reaches consensus. The RFC +makes it through a week-long FCP process. The PR is merged and the stage +is now [Accepted](#Accepted). ### 2 - Accepted -@pzuraq works on implementation. The feature is enabled in canary under feature flag. -We learn that the feature causes a behavior regression in the interop story. +@pzuraq works on implementation. The feature is enabled in canary under feature flag. +We learn that the feature causes a behavior regression in the interop story. @pzuraq works out a new plan to accommodate interop, then opens a PR to update the RFC prose. -The implementation is complete. There are API docs. A PR is opened to move the proposal to -[Ready for Release](#Ready-for-Release). It includes a list of criteria required +The implementation is complete. There are API docs. A PR is opened to move the proposal to +[Ready for Release](#Ready-for-Release). It includes a list of criteria required for this feature to be [Recommended](#Recommended). -On the PR to move to [Ready for Release], each Ember team is requested as a reviewer. -Each team reviews the RFC and implementation, ensuring that any changes to the +On the PR to move to [Ready for Release], each Ember team is requested as a reviewer. +Each team reviews the RFC and implementation, ensuring that any changes to the projects they are responsible for have been completed and that the criteria for -[Recommended](#Recommended) also considers those areas. After a successful FCP +[Recommended](#Recommended) also considers those areas. After a successful FCP period, the PR is merged and the stage is now [Ready for Release](#Ready-for-Release). ### 3 - Ready for Release -The mechanics of releasing the feature proceed. The feature proceeds through +The mechanics of releasing the feature proceed. The feature proceeds through Ember.js' beta cycle. The next stable of Ember.js is released with the feature available. The API docs are published. A PR to update the stage to [Released](#Released) -and the frontmater with release details is opened and merged with the consensus +and the frontmater with release details is opened and merged with the consensus of the framework team. ### 4 - Released @@ -313,19 +316,19 @@ carry through the concepts of 'Tracked Properties' to the tutorial and guides. C to API doc examples are prepared. Other criteria for moving to Recommended are worked on, as defined in the [Ready for Release](#Ready-for-Release) step. This work is documented on a PR to move the proposal to [Recommended](#Recommended). This proposal, along with -several others, are PRed to move to Recommended at the same time, -as part of Octane around Ember.js 3.14. It is determined that the features are not +several others, are PRed to move to Recommended at the same time, +as part of Octane around Ember.js 3.14. It is determined that the features are not yet polished enough and criteria to get to Recommended has not yet been met. More work proceeds and the features are again proposed as Recommended -and put into a "FCP for Recommended", it succeeds and the stages of several +and put into a "FCP for Recommended", it succeeds and the stages of several proposals are updated to Recommended as part of the Octane Edition. ### 5 - Recommended The feature is released and suggested for use by the wider Ember community. They should encounter a polished feature that has ecosystem support. The feature should -be well represented in learning materials and the guides, tutorial and API docs -use the feature in a consistent manner. +be well represented in learning materials and the guides, tutorial and API docs +use the feature in a consistent manner. How was the actual process different from the imaginary case study above? In reality, there were two separate RFCs needed to land the feature, and there were fewer opportunities for people to follow along, give input, and understand the status. @@ -407,5 +410,5 @@ There are some ambiguities because RFCs take many forms. Our process cannot cove ## Glossary -- **FCP**: "final comment period" An FCP is an opportunity for the community and +- **FCP**: "final comment period" An FCP is an opportunity for the community and core team members to weight in before an RFC moves a following stage. diff --git a/text/0625-helper-managers.md b/text/0625-helper-managers.md index fb07a73deb..62dabd3d53 100644 --- a/text/0625-helper-managers.md +++ b/text/0625-helper-managers.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-04-28 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/625 diff --git a/text/0626-invoke-helper.md b/text/0626-invoke-helper.md index aac6bf3955..85af9fac22 100644 --- a/text/0626-invoke-helper.md +++ b/text/0626-invoke-helper.md @@ -1,5 +1,9 @@ --- +Stage: Recommended Start Date: 2020-04-30 +Release Date: FIXME +Release Versions: + ember-source: v3.23.0 Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/626 diff --git a/text/0628-prettier.md b/text/0628-prettier.md index 667f0464f0..e93655d222 100644 --- a/text/0628-prettier.md +++ b/text/0628-prettier.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2020-05-18 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/628 diff --git a/text/0631-refresh-method-for-router-service.md b/text/0631-refresh-method-for-router-service.md index f2190193ef..9ce04f3fde 100644 --- a/text/0631-refresh-method-for-router-service.md +++ b/text/0631-refresh-method-for-router-service.md @@ -1,5 +1,9 @@ --- +# FIXME: May be Recommended +Stage: Released Start Date: 2020-05-23 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/631 @@ -53,7 +57,7 @@ The following documentation will be added to the method: * Returns a promise that will be resolved once the refresh is complete. * All resetController, beforeModel, model, afterModel, redirect, and setupController * hooks will be called again. You will get new data from the model hook. - * + * * @method refresh * @param {String} [pivotRouteName] the route to refresh (along with all child routes) * @return Transition diff --git a/text/0635-ember-new-lang.md b/text/0635-ember-new-lang.md index f8b35e4b51..292c578090 100644 --- a/text/0635-ember-new-lang.md +++ b/text/0635-ember-new-lang.md @@ -1,5 +1,9 @@ --- +# FIXME: May be recommended +Stage: Released Start Date: 2020-05-29 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): CLI, Learning RFC PR: https://github.com/emberjs/rfcs/pull/635 Authors: Joseph Sumner, Ava Wroten, Jamie White, Melanie Sumner @@ -24,7 +28,7 @@ This RFC and its proposed approach have both been developed within the Ember.js > > **Source: [WCAG Success Criterion 3.1.1: Intent](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html#intent)** -When the language of the page cannot be identified, the integrity of the above information cannot be guaranteed. +When the language of the page cannot be identified, the integrity of the above information cannot be guaranteed. Consider the following use case: - the application developer is unaware that Ember now includes the lang attribute @@ -48,14 +52,14 @@ To see what happens when this information does not match, we created a new Ember If no lang attribute is set for the page or the parts: - the screen reader defaults to the operating system (OS) language -- it reads Spanish in an English accent, and the button element was also still read in English +- it reads Spanish in an English accent, and the button element was also still read in English - for the Chinese and Russian letters, it spelled out the letters (i.e., "Cyrillic Letter E") #### Language Defined We then changed the lang attribute value and listened to these buttons in Chinese(zh), Spanish(es) and Russian(ru). Here's what happened: -- in each case, the announcer's voice changed for the content +- in each case, the announcer's voice changed for the content - since the OS was set to English, the supporting element information that the assistive tech (AT) announces was in the OS language (English) - when set to Chinese, the AT read the English, Chinese and Spanish well enough to understand, but did not read out the Russian; likewise, Russian behaved similarly (read all of them except the Chinese) @@ -83,7 +87,7 @@ Accordingly, while the primary motivation of this RFC is to address an unresolve Link to [candidate implementation](https://github.com/josephdsumner/ember-cli/compare/master...ember-new-lang-base). -We have explicitly chosen `--lang` as the flag (vs `--language`) for consistency with the HTML attribute itself. +We have explicitly chosen `--lang` as the flag (vs `--language`) for consistency with the HTML attribute itself. ```bash ember new my-app --lang en-US @@ -187,13 +191,13 @@ Information about using the `--lang` flag: 2. Update the [Ember.js CLI Guides](https://cli.emberjs.com/release/basic-use/cli-commands/) to reflect the new flag much like we demonstrate `--yarn` usage. 3. Update the Ember CLI `--help` command so it explains what kind of value is expected to be passed to the `--lang` flag. 4. Update the Super Rental tutorial to include updated information. -5. Update the Guides - specifically the section that discusses the language attribute. +5. Update the Guides - specifically the section that discusses the language attribute. ### For the Ember CLI Guides: The `--lang` flag can be used to set the spoken language of the app or addon. -To use with a language code only, this is the syntax that would be used: +To use with a language code only, this is the syntax that would be used: ```bash ember new my-app --lang en @@ -229,7 +233,7 @@ The popular [localization library ember-intl](https://github.com/ember-intl/embe * Users may be confused about whether or not they are supposed to specify a human language or a programming language (i.e. `--lang typescript`). However, we think we've mitigated this by using the HTML attribute as the flag name, and having helpful error messages that guide developers in the right direction. ## Alternatives -These are the alternative approaches that we are aware of; if more become apparent in discussion, this RFC will be updated to include them. +These are the alternative approaches that we are aware of; if more become apparent in discussion, this RFC will be updated to include them. - Set the default html lang attribute to `en-US` (the language of the Ember.js project) and assume users will either change the `lang` value themselves, or rely exclusively on `ember-intl` (and not just for apps that require full globalization). - [Valuable discussion points in this issue](https://github.com/emberjs/rfcs/issues/595) diff --git a/text/0637-customizable-test-setups.md b/text/0637-customizable-test-setups.md index ca75be07eb..1e8c5c3f95 100644 --- a/text/0637-customizable-test-setups.md +++ b/text/0637-customizable-test-setups.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-06-01 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember-CLI RFC PR: https://github.com/emberjs/rfcs/pull/637 @@ -13,28 +17,28 @@ Provide a default and convenient way for each project to customize the `setupApplicationTest`, `setupRenderingTest`, and `setupTest` functions from [RFC #268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) and [RFC #232](https://github.com/emberjs/rfcs/blob/master/text/0232-simplify-qunit-testing-api.md). -The app and addon blueprints will be updated to create a file at -`tests/helpers/index.js` where those functions will be wrapped and exported, -creating a local place to edit for each type of test setup. Tests generated +The app and addon blueprints will be updated to create a file at +`tests/helpers/index.js` where those functions will be wrapped and exported, +creating a local place to edit for each type of test setup. Tests generated using `ember generate` will import the setup functions from that file. ## Motivation -Projects often need to customize setup for every test. For example, in +Projects often need to customize setup for every test. For example, in acceptance tests, it is often necessary to override services, mock APIs, etc. in every test of that type. A common use-case is `ember-cli-mirage`, which provides a `setupMirage` function -to be called after `setupApplicationTest`. In a project using this, it can be +to be called after `setupApplicationTest`. In a project using this, it can be necessary to remember to add that call to every test file. -If it is necessary to add new setup to every test (for example, when adding a -service that must be replaced in test), every test file must be individually +If it is necessary to add new setup to every test (for example, when adding a +service that must be replaced in test), every test file must be individually modified. -For these reasons, many projects create their own `setup*Test` functions in the -`test/helpers` directory, either wrapping the addon-provided `setup*Test` +For these reasons, many projects create their own `setup*Test` functions in the +`test/helpers` directory, either wrapping the addon-provided `setup*Test` functions or composing with them in each test file. For example: @@ -42,7 +46,7 @@ For example: ```js import { module, test } from 'qunit'; import setupTest from 'ember-qunit'; - + module('Unit | Service | tomster', function(hooks) { setupTest(hooks); @@ -56,10 +60,10 @@ manually be changed to: ```js import { module, test } from 'qunit'; import setupTest from 'my-app/tests/helpers'; - + module('Unit | Service | tomster', function(hooks) { setupTest(hooks); - + test('this works', function(//... }); ``` @@ -70,7 +74,7 @@ or where the setup functions are to be composed, this must be added: import { module, test } from 'qunit'; import setupTest from 'ember-qunit'; import setupMyTest from 'my-app/tests/helpers'; - + module('Unit | Service | tomster', function(hooks) { setupTest(hooks); setupMyTest(hooks); @@ -80,7 +84,7 @@ or where the setup functions are to be composed, this must be added: ``` Developers of these projects must remember to change the imports or additionally -call their custom setup in every test file. It is easy to forget to make these +call their custom setup in every test file. It is easy to forget to make these changes and waste time to debug test failures or weird test side effects. ## Detailed design @@ -100,73 +104,73 @@ export { setupTest, setupRenderingTest } from 'ember-qunit'; The current imports in newly generated tests: ```js -import { setupApplicationTest } from 'ember-qunit'; +import { setupApplicationTest } from 'ember-qunit'; // OR import { setupRenderingTest } from 'ember-qunit'; // OR import { setupTest } from 'ember-qunit'; ``` -will change in the relevant generated tests to: +will change in the relevant generated tests to: ```js -import { setupApplicationTest } from 'my-app-name/tests/helpers'; +import { setupApplicationTest } from 'my-app-name/tests/helpers'; // OR import { setupRenderingTest } from 'my-app-name/tests/helpers'; // OR import { setupTest } from 'my-app-name/tests/helpers'; ``` -`ember-qunit` has been used for demonstrative purposes, but the blueprints for -generated tests using `ember-mocha` are also maintained in `ember-source` -and `ember-data`. Those blueprints will also be updated to use the local test -helpers. The `test/helpers/index.js` file will import from the appropriate +`ember-qunit` has been used for demonstrative purposes, but the blueprints for +generated tests using `ember-mocha` are also maintained in `ember-source` +and `ember-data`. Those blueprints will also be updated to use the local test +helpers. The `test/helpers/index.js` file will import from the appropriate test framework. -We will provide a codemod to update existing tests. @rwjblue has created a +We will provide a codemod to update existing tests. @rwjblue has created a [proof-of-concept codemod](https://astexplorer.net/#/gist/ba7e5ae104aac099bc5ca60ef874eb74/fc6cd9ad60df7abf17813136d7cdc75b0f313496). An `eslint-plugin-ember` lint rule will be created to solely allow the imports -of `setup*Test` directly from `ember-qunit`/`ember-mocha` in the +of `setup*Test` directly from `ember-qunit`/`ember-mocha` in the `test/helpers/index.js` file. ## How we teach this The Ember.js guides extensively cover testing and use the `setup*Test` functions. -Those guides will need to be updated to reflect the new imports that will be in -generated tests. Because of this, the guides will need to explain the file at +Those guides will need to be updated to reflect the new imports that will be in +generated tests. Because of this, the guides will need to explain the file at `test/helpers/index.js` as a place for customization. The tutorial also covers testing, using the `setup*Test` functions. It will need to be updated, as other existing Ember apps will, likely by using the codemod. -This change will not substantially alter how a developer new to Ember would +This change will not substantially alter how a developer new to Ember would learn and use the framework. ## Drawbacks Developers will need to trace imports through the local file before finding the -the bulk of the setup methods come from `ember-qunit` or `ember-mocha`. -Projects without a need to customize the behavior of these test setup functions -may find that slightly inconvenient. +the bulk of the setup methods come from `ember-qunit` or `ember-mocha`. +Projects without a need to customize the behavior of these test setup functions +may find that slightly inconvenient. ## Alternatives -We could leave it to each project, as we do now, to create helpers to customize -behavior as needed. The downsides of this current state would remain as +We could leave it to each project, as we do now, to create helpers to customize +behavior as needed. The downsides of this current state would remain as discussed in [Motivation](#Motivation). Another alternative would be to create base classes from which test modules could extend, similar to how it is done within [`Ember.js`](https://github.com/emberjs/ember.js/blob/master/packages/internal-test-helpers/lib/test-cases/application.js). -This would be a much larger change to how we write tests in Ember projects and -would have many details to be discussed and hashed out. It may be worth exploring -but the change proposed in this RFC would still provide value until that idea +This would be a much larger change to how we write tests in Ember projects and +would have many details to be discussed and hashed out. It may be worth exploring +but the change proposed in this RFC would still provide value until that idea were realized. ### Prior Art A very similar proposal was discussed in -[a CLI Issue](https://github.com/ember-cli/ember-cli/pull/7657), over two years +[a CLI Issue](https://github.com/ember-cli/ember-cli/pull/7657), over two years ago. ## Unresolved questions diff --git a/text/0638-interactive-app-creation.md b/text/0638-interactive-app-creation.md index 8acb70b195..70f1f63019 100644 --- a/text/0638-interactive-app-creation.md +++ b/text/0638-interactive-app-creation.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-06-12 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): ember-cli, framework, learning RFC PR: https://github.com/emberjs/rfcs/pull/638 @@ -9,18 +13,18 @@ RFC PR: https://github.com/emberjs/rfcs/pull/638 ## Summary -As part of the effort to make new Ember apps more conformant for digital accessibility requirements at a global scale, this RFC proposes an interactive workflow for new Ember apps. This will also have the benefit of assisting new users who prefer an interactive model of new app creation. +As part of the effort to make new Ember apps more conformant for digital accessibility requirements at a global scale, this RFC proposes an interactive workflow for new Ember apps. This will also have the benefit of assisting new users who prefer an interactive model of new app creation. ## Motivation -This RFC is the result of [analysis and discussion in Ember's accessibility strike team](https://github.com/ember-a11y/core-notes/blob/ember-a11y/ember-a11y/2020-05/may-20.md). The overall roadmap for addressing this issue is with a series of RFCs that intend to (independently) offer: +This RFC is the result of [analysis and discussion in Ember's accessibility strike team](https://github.com/ember-a11y/core-notes/blob/ember-a11y/ember-a11y/2020-05/may-20.md). The overall roadmap for addressing this issue is with a series of RFCs that intend to (independently) offer: * a partial resolution to ensuring new Ember apps achieve [WCAG Success Criteria 3.1.1 (language of the page)](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html) * enhancements to Ember CLI that empower developers to make their applications more accessible-by-default * global improvements to new Ember applications (i.e., improvements gained by achieving WCAG SC-3.1.1 that aren't specifically related to digital accessibility) The underlying motivation for this RFC is the desire to improve the accessibility of new Ember apps as [previously documented in Issue 595/Section 4](https://github.com/emberjs/rfcs/issues/595). Specifically, it aims to prevent new Ember apps from failing legal requirements for accessibility conformance according to [WCAG 2.1](https://w3c.github.io/wcag/21/guidelines/), the standard used by most countries around the world to inform digital accessibility requirements. In that context, this RFC seeks to help new Ember applications achieve [WCAG Success Criteria 3.1.1: language of page](https://www.w3.org/TR/WCAG21/#language-of-page) by providing users of `ember-cli` to specify the base human language of their new application within an interactive setup workflow. -That being said, the overall developer experience improvement is the primary motivation. Interactive app creation helps new developers understand the important decisions they must make, and safely explore the options that they have (as defined in the question options). This provides a learning environment that will help build up the confidence of the new Ember developer by providing them with an interactive environment and helpful feedback during troubleshooting and error handling, thus flattening the learning curve. This will also help more experienced developers move faster; the strong defaults that Ember is known for will make it even easier than before to set up a new repo with the confidence that the important things are not being forgotten. +That being said, the overall developer experience improvement is the primary motivation. Interactive app creation helps new developers understand the important decisions they must make, and safely explore the options that they have (as defined in the question options). This provides a learning environment that will help build up the confidence of the new Ember developer by providing them with an interactive environment and helpful feedback during troubleshooting and error handling, thus flattening the learning curve. This will also help more experienced developers move faster; the strong defaults that Ember is known for will make it even easier than before to set up a new repo with the confidence that the important things are not being forgotten. ## Detailed design @@ -29,39 +33,39 @@ The first step of the solution was presented in [RFC 635](https://github.com/emb ### Prior Art It would be remiss to introduce this RFC without mentioning the prior art that we analyzed for wizard-like app creation. In the Ember community, [@gossi](https://gist.github.com/gossi) first introduced this idea with [ember-cli-create](https://github.com/gossi/ember-cli-create). In the wider web community, the Vue community offers this through `vue create` ([see docs](https://cli.vuejs.org/guide/creating-a-project.html#vue-create)). -### Intro -When considering what questions to ask, we considered a few things: +### Intro +When considering what questions to ask, we considered a few things: 1. What questions do we have to ask ourselves every time we create a new Ember app? 1. How many questions do we think developers will tolerate? 1. Should the questions be different if it is an app vs addon? We will also endeavor to provide strong defaults for these questions, based on the results from the community surveys we have been conducting over the past few years and the defaults as stated by Ember itself (either explicitly or implicitly). **If these defaults change over time as the result of community RFCs, the default values or other responses for the interactive questions should be updated as part of those RFCs.** -So, how then do we decide which questions to include and which not to include? It became necessary to then develop a rubric by which the proposed list of questions could be measured. +So, how then do we decide which questions to include and which not to include? It became necessary to then develop a rubric by which the proposed list of questions could be measured. ### Question Rubric -We intend for this section to be normative; that is, we intend for it to define how questions are evaluated for inclusion both now and in the future. +We intend for this section to be normative; that is, we intend for it to define how questions are evaluated for inclusion both now and in the future. -Evaluating criteria: -1. Is it a choice that is hard (or time-consuming) to change one's mind about later? *For example, it's easy to remove the `ember-welcome-page` addon, so we did not include it. But it's time consuming to change from `yarn` to `npm` (or vice-versa) so we made sure to include that.* +Evaluating criteria: +1. Is it a choice that is hard (or time-consuming) to change one's mind about later? *For example, it's easy to remove the `ember-welcome-page` addon, so we did not include it. But it's time consuming to change from `yarn` to `npm` (or vice-versa) so we made sure to include that.* 1. Is it difficult to discover the option? -1. What is the maintenance cost? *For example, a nice question to add could be something like, Do you want to use a CSS preprocessor? But, because Ember does not deal with SASS, LESS... by default, the interactive workflow will have to install an addon (like `ember-cli-less`) which would imply that the CLI team will have to ensure it never fails.* +1. What is the maintenance cost? *For example, a nice question to add could be something like, Do you want to use a CSS preprocessor? But, because Ember does not deal with SASS, LESS... by default, the interactive workflow will have to install an addon (like `ember-cli-less`) which would imply that the CLI team will have to ensure it never fails.* 1. Does the question affect another one? *For example, the LTS question can affect the CI file generated by the CI question (setup tests on CI with `ember-try`). Questions that modify the result of other questions too much should be avoided to prevent high maintenance.* ### Triggering the Workflow -The following commands, and reasonable combinations thereof, should work to enter into the interactive workflow: +The following commands, and reasonable combinations thereof, should work to enter into the interactive workflow: 1. `ember new` 1. `ember new --interactive` 1. `ember new -i` 1. `ember new my-app -i` -### App/Addon +### App/Addon -Starting a new Ember app or addon as we do now (at the time of this writing) will not change. If a user types `ember new my-app` they will still get a new Ember app generated in the usual ways. However, if the user types `ember new` they will enter into an interactive workflow that will ask them a few key questions about their application. +Starting a new Ember app or addon as we do now (at the time of this writing) will not change. If a user types `ember new my-app` they will still get a new Ember app generated in the usual ways. However, if the user types `ember new` they will enter into an interactive workflow that will ask them a few key questions about their application. -If a user were to type in existing flags that are also questions in the interactive workflow (i.e., `ember new my-app --lang en-US --interactive`), it will skip the question entirely. +If a user were to type in existing flags that are also questions in the interactive workflow (i.e., `ember new my-app --lang en-US --interactive`), it will skip the question entirely. When a user types `ember new` into their command line, they will be asked these questions (defaults indicated by a `>`): @@ -82,31 +86,31 @@ When a user types `ember new` into their command line, they will be asked these - `ignore/skip` #### App/Addon Name -There will be no default for this question. The user must enter a response. +There will be no default for this question. The user must enter a response. #### App/Addon Language - the default would be `en-US` - if your system has a different language set (which can be confirmed by using the `echo $LANG` command in the terminal), then _that_ language would be shown as the second option -- if your system was already set to the default language, the second option would not be shown. +- if your system was already set to the default language, the second option would not be shown. - for "manually define a language", we will validate the response against the allowed language codes - we have not added a "skip" option here, because the purpose is to focus on improved accessibility in Ember apps. #### Package Manager -- ignore/skip has been added to cover the use case where the developer is in a workspace +- ignore/skip has been added to cover the use case where the developer is in a workspace #### CI Option -Separate RFCs should further define more options for CI. - +Separate RFCs should further define more options for CI. + ### Current Limitations Explicitly, the goal of this RFC is to only include `ember-cli` flags that already exist. Any other possibilities should be considered future work. This interactive workflow will also ignore any ~/.ember-cli settings that already exist. A separate RFC should be written that makes it possible for these to things to co-exist and respect the settings of the other. ### Future possibilities -An example of a future RFC that could be specific to addons, would be to add a `--supported-version` flag for addons and add that to the wizard: +An example of a future RFC that could be specific to addons, would be to add a `--supported-version` flag for addons and add that to the wizard: - `What is the earliest version of Ember that you intend to support? (use arrow keys)` - `> recommended (last two LTS)` @@ -114,20 +118,20 @@ An example of a future RFC that could be specific to addons, would be to add a ` - `manually define a version number` ### Implementation -This section is not normative, but provided for extra context for folks who might be new to this idea in general. We could use something like [inquirer.js](https://github.com/SBoudrias/Inquirer.js) to implement this wizard, if the mechanism doesn't already exist within the ember-cli codebase. However, it should be explicitly noted that inquirer is only being used as an example of a library that could be used, and this RFC isn't explicitly defining that inquirer.js should be or will be used. +This section is not normative, but provided for extra context for folks who might be new to this idea in general. We could use something like [inquirer.js](https://github.com/SBoudrias/Inquirer.js) to implement this wizard, if the mechanism doesn't already exist within the ember-cli codebase. However, it should be explicitly noted that inquirer is only being used as an example of a library that could be used, and this RFC isn't explicitly defining that inquirer.js should be or will be used. ### Versioning and Stability Statement -Because the `ember new` command only affects new apps, it is not subject to the same semver guarantees that official Ember.js framework libraries currently follow. +Because the `ember new` command only affects new apps, it is not subject to the same semver guarantees that official Ember.js framework libraries currently follow. -The `ember new` interactive workflow SHOULD NOT be used in other scripts; it is the intent of the design to make this workflow flexible and changeable over time. As such, it should not be considered stable enough to be integrated into other automated tooling. Users should continue to make use of the commands available via `ember-cli` for any other integration scripts. +The `ember new` interactive workflow SHOULD NOT be used in other scripts; it is the intent of the design to make this workflow flexible and changeable over time. As such, it should not be considered stable enough to be integrated into other automated tooling. Users should continue to make use of the commands available via `ember-cli` for any other integration scripts. ## How we teach this -As this is a wholly new idea, it should be documented and added to the guides along with screenshots of the new workflow. Until that prototype exists, this section will largely remain empty. However, we intend to explain it similarly to Vue's documentation for a similar feature (https://cli.vuejs.org/guide/creating-a-project.html#vue-create). +As this is a wholly new idea, it should be documented and added to the guides along with screenshots of the new workflow. Until that prototype exists, this section will largely remain empty. However, we intend to explain it similarly to Vue's documentation for a similar feature (https://cli.vuejs.org/guide/creating-a-project.html#vue-create). ## Drawbacks -It could be considered a drawback to make this not the default for new Ember apps, even if an app name is defined. +It could be considered a drawback to make this not the default for new Ember apps, even if an app name is defined. The general drawback with wizards is that it can lead to a large number of combinations, which increases the risk for fragmentation. We believe that we have limited this risk by limiting the number of questions asked, but it is still a risk and should be identified as such. @@ -141,4 +145,4 @@ The general drawback with wizards is that it can lead to a large number of combi ## Unresolved questions -As we identify additional unresolved questions, we will add them here. +As we identify additional unresolved questions, we will add them here. diff --git a/text/0639-replace-blacklist-whitelist.md b/text/0639-replace-blacklist-whitelist.md index e26b173c11..aef7ad68de 100644 --- a/text/0639-replace-blacklist-whitelist.md +++ b/text/0639-replace-blacklist-whitelist.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be a further stage +Stage: Accepted Start Date: 2020-06-15 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI, Learning RFC PR: https://github.com/emberjs/rfcs/pull/639 diff --git a/text/0645-add-ember-page-title-addon.md b/text/0645-add-ember-page-title-addon.md index 4db2e3a4c8..6cf89dc0ae 100644 --- a/text/0645-add-ember-page-title-addon.md +++ b/text/0645-add-ember-page-title-addon.md @@ -1,5 +1,8 @@ --- +Stage: Recommended Start Date: 2020-06-24 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/645 Authors: Benjamin Jegard, Melanie Sumner, Ricardo Mendes diff --git a/text/0649-deprecation-staging.md b/text/0649-deprecation-staging.md index 4766b2a8bc..112380ee2b 100644 --- a/text/0649-deprecation-staging.md +++ b/text/0649-deprecation-staging.md @@ -1,5 +1,9 @@ --- +# FIXME: This seems to be at least partially implemented +Stage: Accepted Start Date: 2020-06-18 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js, Learning, Steering, Ember CLI RFC PR: https://github.com/emberjs/rfcs/pull/649 diff --git a/text/0659-unique-id-helper.md b/text/0659-unique-id-helper.md index e9862248af..8e21f2d8a6 100644 --- a/text/0659-unique-id-helper.md +++ b/text/0659-unique-id-helper.md @@ -1,5 +1,9 @@ --- +# FIXME: This may be Recommended +Stage: Released Start Date: 2020-08-25 +Release Date: FIXME +Release Versions: FIXME Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/659 @@ -32,7 +36,7 @@ Add built-in `{{unique-id}}` template helper. The `unique-id` helper can be invoked with no arguments. When invoked this way, the `unique-id` helper will return a new unique id string for every invocation. -In practice this invocation style would usually be paired with a `let` block to enable re-use of the unique id generated by `{{unique-id}}`. +In practice this invocation style would usually be paired with a `let` block to enable re-use of the unique id generated by `{{unique-id}}`. ```hbs {{#let (unique-id) as |emailId|}} @@ -59,11 +63,11 @@ The `{{unique-id}}` helper can be implemented using the existing mechanisms Embe The Ember API docs can be updated to include the `unique-id` helper on the page for [Ember.templates.helpers](https://api.emberjs.com/ember/release/classes/Ember.Templates.helpers) > Use the `{{unique-id}}` helper to generate a unique ID string suitable for use as an ID attribute in the DOM. -> +> > ```hbs > > ``` -> +> > Each invocation of `{{unique-id}}` will return a new, unique ID string. You can use the `let` helper to create an ID that can be reused within a template. > ```hbs > {{#let (unique-id) as |emailId|}} @@ -79,7 +83,7 @@ The Ember guides currently include a section on associating labels and inputs. T [Guides: associating labels and inputs](https://guides.emberjs.com/release/components/built-in-components/#toc_ways-to-associate-labels-and-inputs) > Every input should be associated with a label. Within HTML, there are several different ways to do this. In this section, we will show how to apply those strategies for Ember inputs. -> +> > You can nest the input inside the label: > ```hbs > > > ``` -> +> > In HTML, each element's id attribute must be a value that is unique within the HTML document. Ember provides the built-in `{{unique-id}}` helper to assist you with generating unique IDs. > ```hbs @@ -105,12 +109,12 @@ The Ember guides currently include a section on associating labels and inputs. T > > {{/let}} > ``` -> +> > The `aria-label` attribute enables developers to label an input element with a string that is not visually rendered, but still available to assistive technology. > ```hbs > > ``` -> +> > While it is more appropriate to use a