From ffd4fd445b3b559c1539e8d764f49b88260ae817 Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Thu, 14 Jan 2021 15:46:25 -0800 Subject: [PATCH 1/3] Deprecate the Ember Global --- text/0000-deprecate-ember-global.md | 104 ++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 text/0000-deprecate-ember-global.md diff --git a/text/0000-deprecate-ember-global.md b/text/0000-deprecate-ember-global.md new file mode 100644 index 0000000000..e67faa02f0 --- /dev/null +++ b/text/0000-deprecate-ember-global.md @@ -0,0 +1,104 @@ +--- +Stage: Accepted +Start Date: 2020-14-01 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: +--- + +# Deprecate the Ember Global + +## Summary + +Deprecate the Ember global, `window.Ember`, and replace it fully with +`import Ember from 'ember';` + +## Motivation + +The Ember global, available at `window.Ember` (or `globalThis.Ember` in all +environments) is a mostly legacy API from before Ember adopted native ES +modules. Modern Ember apps do not use the global, and in general it is mostly +used by legacy code and occasionally in examples. However, it still exists and +remains undeprecated. + +The primary motivation for deprecating the global object is for _tree shaking_ +purposes. Because the global object is assigned eagerly to `window.Ember` +whenever Ember is loaded, it essentially means that every Ember application +implicitly uses every single API that is exported on the global object. This +means that we cannot tree shake any of those APIs, and we must in fact load them +all eagerly and execute all of their code as soon as Ember is loaded. + +While it is tempting to remove the `Ember` object altogether, there are a number +of undeprecated legacy and intimate APIs that are only available through this +object, such os `Ember.meta`. This is why this RFC proposes only deprecating +accessing `Ember` _via_ `window.Ember`/`globalThis.Ember`. Instead, users will +have to import `Ember` using standard ES module syntax if they want to use it. + +```js +import Ember from 'ember'; +``` + +This ensures there is an _explicit_ dependency if it is used, and which will +allow us to treeshake in the future if nothing imports `Ember`. In time, we will +be able to deprecate the `Ember` object altogether. + +## Detailed design + +When the `Ember` object is defined on the global, we will create a getter for it +that also issues a deprecation. + +## How we teach this + +### Deprecation Guide + +Accessing Ember on the global context (e.g. `window.Ember`, `globalThis.Ember`, +or just `Ember` without importing it) is no longer supported. Migrate to +importing Ember explicitly instead. + +Before: + +```js +export default class MyComponent extends Ember.Component { + // ... +} +``` + +After: + +```js +import Ember from 'ember'; + +export default class MyComponent extends Ember.Component { + // ... +} +``` + +Alternatively, consider converting to use the Ember modules API equivalent to +the API you are using: + +```js +import Component from '@ember/component'; + +export default class MyComponent extends Component { + // ... +} +``` + +If there is no modules API equivalent, consider refactoring away from using that +API. + +## Drawbacks + +- Introduces churn in legacy codebases + +- Some polyfills and addons use `Ember` in places where the modules API is not + available, such as in `vendor` files. These are advanced use cases in general, + and there are possible workarounds (such as using the `require` global + function), so this shouldn't block us from removing the global. + +## Alternatives + +- Keep the global indefinitely. From 88fc660806bcb6bd46b2cd7f696e604f8e3df8a2 Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Thu, 14 Jan 2021 15:47:17 -0800 Subject: [PATCH 2/3] rename and add PR --- ...deprecate-ember-global.md => 0706-deprecate-ember-global.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-deprecate-ember-global.md => 0706-deprecate-ember-global.md} (98%) diff --git a/text/0000-deprecate-ember-global.md b/text/0706-deprecate-ember-global.md similarity index 98% rename from text/0000-deprecate-ember-global.md rename to text/0706-deprecate-ember-global.md index e67faa02f0..5d183a8bae 100644 --- a/text/0000-deprecate-ember-global.md +++ b/text/0706-deprecate-ember-global.md @@ -6,7 +6,7 @@ Release Versions: ember-source: vX.Y.Z ember-data: vX.Y.Z Relevant Team(s): Ember.js -RFC PR: +RFC PR: https://github.com/emberjs/rfcs/pull/706 --- # Deprecate the Ember Global From 530d04b3bc8e1339f7144630765f895da3da97fa Mon Sep 17 00:00:00 2001 From: Chris Garrett Date: Thu, 14 Jan 2021 15:57:06 -0800 Subject: [PATCH 3/3] Add more detail to transition path --- text/0706-deprecate-ember-global.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/text/0706-deprecate-ember-global.md b/text/0706-deprecate-ember-global.md index 5d183a8bae..178b0101cd 100644 --- a/text/0706-deprecate-ember-global.md +++ b/text/0706-deprecate-ember-global.md @@ -45,10 +45,11 @@ This ensures there is an _explicit_ dependency if it is used, and which will allow us to treeshake in the future if nothing imports `Ember`. In time, we will be able to deprecate the `Ember` object altogether. -## Detailed design +## Transition Path When the `Ember` object is defined on the global, we will create a getter for it -that also issues a deprecation. +that also issues a deprecation. Users who currently use the global will have to +add `import Ember from 'ember';` at the top of the files in which they use it. ## How we teach this