From 23509d55e772fc8507443bbf18d513c31e736c68 Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 00:39:47 +0000 Subject: [PATCH 1/9] Control transpilation --- active/0000-control-transpilation.md | 75 ++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 active/0000-control-transpilation.md diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md new file mode 100644 index 0000000..56693df --- /dev/null +++ b/active/0000-control-transpilation.md @@ -0,0 +1,75 @@ +- Start Date: (fill me in with today's date, YYYY-MM-DD) +- RFC PR: (leave this empty) +- Ember CLI Issue: (leave this empty) + +# Summary + +Allow consumer apps to control the transpilation not only of application code, but also +of addon code. + +# Motivation + +At the moment addons control their own transpilation process. This is nice for having a +"just works" experience, but leaves users without control over the transpiled code they +ship. + +By example, users might want to opt-out from transpiling certain features because +the application is going to be targeted to fully capable ES6 browsers is still shipping +ES5 code of their addons, regardless of the babel settings of the app. This leads to +bundles more verbose than really required. + +The generator functions used by ember-concurrency is a good example of an utterly verbose +transpiled code that users might not want. + +The goal of this RFC is to make EmberCLI honor the user's preferences for transpilation (through +`ember-cli-babel` or perhaps `typescript`). + +# Detailed design + +The proposed change in behaviour is to apply the user's preferences to the transpilation +of the `addon` tree instead of the addon's configuration. The addon's configuration is +honored by their dummy app only. +For a overwhelming majority of the addons that just use the default settings they won't +notice anything. + +There might be a small number of addons that do customize the settings used by ember-cli-babel, +and there is where some action is required. + +The suggested approach allow addons to access the babeljs configuration so, if they require +an experimental feature enabled to work, they can throw a warning (or even a hard failure) +if that feature is not enabled in the host's configuration. + +It would be a responsability of the addon to emit those warnings if needed, so ember-cli must provide +an idiomatic way of accessing the application's configuration. At the moment it is possible +but is somewhat hacky (`_findHost().options.babel`) and is likely going to change once +Babel6 is used, which will probably use a `.babelrc` file for configuration instead of the +current approach as options in the `ember-cli-build.js` file. + +# How We Teach This + +For end users everything will remain the same. +For most addon authors it will not require any change. Only those addons that do unusual +things with babel, like [ember-computed-decorators](https://github.com/rwjblue/ember-computed-decorators/blob/master/ember-cli-build.js) +may want to do something about it. +If they don't do anything, things may or may not work depending on the user's settings, +so it would be sensible for them to inspect the configuration and warn if neccesary. + +Checking if a feature is available is probably not trivial, so `ember-cli-babel` should +expose some helpers that can be required from node-land to verify that the hosts app supports +a given feature. +This can also abstract babel5/6 complexities, presents and such. + +# Drawbacks + +We give the users more control over the transpilation process at the expenses of some complexity +for addon authors that want to use experimental ES2017 features in their addons, leaving +up to them to give a good user experience. + +# Alternatives + +What other designs have been considered? What is the impact of not doing this? + +# Unresolved questions + +Optional, but suggested for first drafts. What parts of the design are still +TBD? From cb5a605fe5bf4e2c79a0dafc35ab55e14f5f2afc Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 14:47:06 +0000 Subject: [PATCH 2/9] Rething RFC --- active/0000-control-transpilation.md | 74 ++++++++++++++++++---------- 1 file changed, 47 insertions(+), 27 deletions(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 56693df..13114f4 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -4,46 +4,66 @@ # Summary -Allow consumer apps to control the transpilation not only of application code, but also + +Allow consumer apps to control the transpilation config not only of application code, but also of addon code. # Motivation -At the moment addons control their own transpilation process. This is nice for having a -"just works" experience, but leaves users without control over the transpiled code they -ship. +Ember-cli as allowed users to write ES6 code and transpile it to ES5/3 since almost the beginning +of the project. It's one of those things that people take for granted. + +Today that is done through `ember-cli-babel`, an addon that is in the default blueprint and +that the huge majority of apps use. -By example, users might want to opt-out from transpiling certain features because -the application is going to be targeted to fully capable ES6 browsers is still shipping -ES5 code of their addons, regardless of the babel settings of the app. This leads to -bundles more verbose than really required. +This transpilation process has some sensitive defaults that work for most people, but also allow +some use configuration for, by example, disable some transformations enabled by default or enable +some experimental ones. -The generator functions used by ember-concurrency is a good example of an utterly verbose -transpiled code that users might not want. +What is less know is that this configuration only affects the application code. The transpilation +of code living in addons is done according to the configuration of those addons. While there is +use-cases for this, particularly addons that want to run their code though a custom babel plugin, +generally speaking the desired transpiled output is something that the end-users should control. -The goal of this RFC is to make EmberCLI honor the user's preferences for transpilation (through -`ember-cli-babel` or perhaps `typescript`). +By example, applications that only target evergreen browsers may want to disable transpilation of +all ES6 feature since moden browsers already ship them. + +This RFC wants to change this behaviour so addons by default honor the host app's preferences, +while allowing those addons to run their own transformations. # Detailed design -The proposed change in behaviour is to apply the user's preferences to the transpilation -of the `addon` tree instead of the addon's configuration. The addon's configuration is -honored by their dummy app only. -For a overwhelming majority of the addons that just use the default settings they won't -notice anything. +The idea is to still allow addons to be in control of their own transpilation process, but +make them honour uses preferenced by default. + +There is three different scenarios for addons: + +#### The addon doesn't care about the transpilation process. +This is the most common common situation. Most addons are authored in ES6 and they don't +mess with the host app's configuration. +Those addons should just transpile their code user the host's apps settings. + +#### Addons that require experimental features +There is two options here. Either addons can unconditionally enable that feature only for their +tree, or it's the user responsability to enable that feature in order to use the addon, with +optionally the addon doing some feature detection to warn (not force) the user to enable that feature. + +By example, an addon that uses `async-await` which right now are only available in Chrome Canary +could either use the host app's configuration plus this feature or it could just assume the user +has enabled it and tell them to do so in the docs. Optionally the addon could do feature detection +(easened by some utilities in `ember-cli-babel` that abstract presets and all that configuration) +to show a warning in the console. + +I believe that the user should have the last word on this, and given the small amount of addons +that actually do this seems that it's reasonable to update them to behave that way. -There might be a small number of addons that do customize the settings used by ember-cli-babel, -and there is where some action is required. +#### Addons that add their custom babel plugins -The suggested approach allow addons to access the babeljs configuration so, if they require -an experimental feature enabled to work, they can throw a warning (or even a hard failure) -if that feature is not enabled in the host's configuration. +The number of addons that does this is even smaller, but one of them is nothing less than Ember Data, +which uses a babel-plugin to strip Heimdall's instrumentation from production builds. -It would be a responsability of the addon to emit those warnings if needed, so ember-cli must provide -an idiomatic way of accessing the application's configuration. At the moment it is possible -but is somewhat hacky (`_findHost().options.babel`) and is likely going to change once -Babel6 is used, which will probably use a `.babelrc` file for configuration instead of the -current approach as options in the `ember-cli-build.js` file. +Since addons remain in control of their transpilation and just reuse the app's configuration, addons +can attach their own plugins. # How We Teach This From 34af1685a1bcc3377561a60fab589935e5702bd7 Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 15:13:31 +0000 Subject: [PATCH 3/9] More updates --- active/0000-control-transpilation.md | 35 ++++++++++++++-------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 13114f4..63e75b7 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -50,12 +50,7 @@ optionally the addon doing some feature detection to warn (not force) the user t By example, an addon that uses `async-await` which right now are only available in Chrome Canary could either use the host app's configuration plus this feature or it could just assume the user -has enabled it and tell them to do so in the docs. Optionally the addon could do feature detection -(easened by some utilities in `ember-cli-babel` that abstract presets and all that configuration) -to show a warning in the console. - -I believe that the user should have the last word on this, and given the small amount of addons -that actually do this seems that it's reasonable to update them to behave that way. +has enabled it and tell them to do so in the docs. #### Addons that add their custom babel plugins @@ -65,19 +60,25 @@ which uses a babel-plugin to strip Heimdall's instrumentation from production bu Since addons remain in control of their transpilation and just reuse the app's configuration, addons can attach their own plugins. +#### How can addons be in charge of their own transpilation and yet honor user preferences? + +Addons should receive a deep clone of the babel (or typscript) configuration defined in the host app, +not the original config, so they can safely modify it without affecting the application. +Each addon receives its own copy so they don't affect other addons either. + +`ember-cli-babel` will use that object as configuration so user's prerenced are honored unless +the addon, very deliverately, chooses not to. + +Making changes in the configuration be scoped to each addon might also avoid some cost where +some plugin added by one addon is used to transpile code outside that addon. + # How We Teach This -For end users everything will remain the same. -For most addon authors it will not require any change. Only those addons that do unusual -things with babel, like [ember-computed-decorators](https://github.com/rwjblue/ember-computed-decorators/blob/master/ember-cli-build.js) -may want to do something about it. -If they don't do anything, things may or may not work depending on the user's settings, -so it would be sensible for them to inspect the configuration and warn if neccesary. - -Checking if a feature is available is probably not trivial, so `ember-cli-babel` should -expose some helpers that can be required from node-land to verify that the hosts app supports -a given feature. -This can also abstract babel5/6 complexities, presents and such. +This has no impact for apps, just for addons. + +Most addons will not require any change. Only those that want to modify this the transpilation +process like [ember-computed-decorators](https://github.com/rwjblue/ember-computed-decorators/blob/master/ember-cli-build.js) +or ember data will have to be updated. # Drawbacks From cb4bc9b829214c27a0ee355441cf5a9ccbfff82e Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 20:03:26 +0000 Subject: [PATCH 4/9] Last changes --- active/0000-control-transpilation.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 63e75b7..80d9eaf 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -62,15 +62,14 @@ can attach their own plugins. #### How can addons be in charge of their own transpilation and yet honor user preferences? -Addons should receive a deep clone of the babel (or typscript) configuration defined in the host app, -not the original config, so they can safely modify it without affecting the application. -Each addon receives its own copy so they don't affect other addons either. +Ember-cli should provide to each addon a deep clone of the configuration defined in the host app +(by example available in `this.options.babel`), and that config is the one used to transpile the addon. -`ember-cli-babel` will use that object as configuration so user's prerenced are honored unless -the addon, very deliverately, chooses not to. +The addon will therefore honor the app's configuration by default, but it can also decide to add +custom plugins, enable specific features or just throw a warning message if the app's config +doesn't have required specific transformation enabled. -Making changes in the configuration be scoped to each addon might also avoid some cost where -some plugin added by one addon is used to transpile code outside that addon. +By modifying this clone, their changes will not affect the host app or other addons. # How We Teach This @@ -88,9 +87,13 @@ up to them to give a good user experience. # Alternatives -What other designs have been considered? What is the impact of not doing this? +None that I can think of, beside of not doing this. # Unresolved questions -Optional, but suggested for first drafts. What parts of the design are still -TBD? +For this approach it doesn't matter if the version of babel is 5 or 6, however the plugins and their +names are funamentally incompatible. + +- Should addons that depend on `ember-cli-babel` be compiled with their version or with the app's version? +- If the version of babel in the addon wins but the host apps uses babel6, the config cannot be shared. In + that case addons should get the default config? From ee22727bcf819435d38e92b420950e7b32644ebc Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 20:04:40 +0000 Subject: [PATCH 5/9] Add date --- active/0000-control-transpilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 80d9eaf..e0ab043 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -1,4 +1,4 @@ -- Start Date: (fill me in with today's date, YYYY-MM-DD) +- Start Date: 2016-12-07 - RFC PR: (leave this empty) - Ember CLI Issue: (leave this empty) From 77e2f3fb25e4196f6a5baec7dfb29fe9af3a8c05 Mon Sep 17 00:00:00 2001 From: cibernox Date: Wed, 7 Dec 2016 20:22:26 +0000 Subject: [PATCH 6/9] Fix many typos --- active/0000-control-transpilation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index e0ab043..3410c23 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -10,17 +10,17 @@ of addon code. # Motivation -Ember-cli as allowed users to write ES6 code and transpile it to ES5/3 since almost the beginning +Ember CLI has allowed users to write ES6 code and transpile it to ES5/3 since almost the beginning of the project. It's one of those things that people take for granted. Today that is done through `ember-cli-babel`, an addon that is in the default blueprint and that the huge majority of apps use. -This transpilation process has some sensitive defaults that work for most people, but also allow +This transpilation process has some sensible defaults that work for most people, but also allow some use configuration for, by example, disable some transformations enabled by default or enable some experimental ones. -What is less know is that this configuration only affects the application code. The transpilation +What is less known is that this configuration only affects the application code. The transpilation of code living in addons is done according to the configuration of those addons. While there is use-cases for this, particularly addons that want to run their code though a custom babel plugin, generally speaking the desired transpiled output is something that the end-users should control. @@ -33,10 +33,10 @@ while allowing those addons to run their own transformations. # Detailed design -The idea is to still allow addons to be in control of their own transpilation process, but -make them honour uses preferenced by default. +The idea is to still have addons control their own transpilation process, but +make them honour user preferences by default. -There is three different scenarios for addons: +There are three different scenarios for addons: #### The addon doesn't care about the transpilation process. This is the most common common situation. Most addons are authored in ES6 and they don't @@ -44,7 +44,7 @@ mess with the host app's configuration. Those addons should just transpile their code user the host's apps settings. #### Addons that require experimental features -There is two options here. Either addons can unconditionally enable that feature only for their +There are two options here. Either addons can unconditionally enable that feature only for their tree, or it's the user responsability to enable that feature in order to use the addon, with optionally the addon doing some feature detection to warn (not force) the user to enable that feature. From d42c79a6940cf2649ef9af7da152f0795995abc1 Mon Sep 17 00:00:00 2001 From: cibernox Date: Mon, 12 Dec 2016 12:44:17 +0000 Subject: [PATCH 7/9] A lot of changes to make clear the focus of the RFC Separate the grain from the hay --- active/0000-control-transpilation.md | 78 ++++++++++++---------------- 1 file changed, 34 insertions(+), 44 deletions(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 3410c23..2a6c607 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -4,9 +4,8 @@ # Summary - -Allow consumer apps to control the transpilation config not only of application code, but also -of addon code. +Change how addon code is transpiled to it honors user preferences by default, but still +allow addons to be in control of the transpilation if they need to. # Motivation @@ -20,13 +19,25 @@ This transpilation process has some sensible defaults that work for most people, some use configuration for, by example, disable some transformations enabled by default or enable some experimental ones. -What is less known is that this configuration only affects the application code. The transpilation -of code living in addons is done according to the configuration of those addons. While there is -use-cases for this, particularly addons that want to run their code though a custom babel plugin, -generally speaking the desired transpiled output is something that the end-users should control. +What is less known is that this configuration only affects the application code (the one in your app +and the code in the `/app` folder of addons). +The transpilation of code living in the `/addon` folder of addons is done according to the +configuration of those addons, which is the default config of ember-cli-babel unless the addons specifies +otherwise. + +The reasoning behind that decission is that addons might have special needs so they have to be in +charge their own transpilation. Some examples of addons that do that are [Ember-data](https://github.com/emberjs/data/blob/master/index.js#L115-L125), +[smoke-and-mirrors](https://github.com/runspired/smoke-and-mirrors/blob/master/index.js#L27-L42). + +However, an undesired side effect of this approach is that, as it stands today, it means that +the configuration of the user is ignored by addons. That means addons will still transpile features +(p.e. generator functions) even if the users have disabled them in their apps because they targets +only evergreen browsers. -By example, applications that only target evergreen browsers may want to disable transpilation of -all ES6 feature since moden browsers already ship them. +With ES6 being fully implemented in all modern browsers and many ES2016/ES2017 already starting to +be appear, seems clear that the transpilation level of apps is a moving target and addons should +obey user configuration by default, as opposed of the current approach of transpiling anything that +is not ES5 despite of what the user wants. This RFC wants to change this behaviour so addons by default honor the host app's preferences, while allowing those addons to run their own transformations. @@ -34,42 +45,22 @@ while allowing those addons to run their own transformations. # Detailed design The idea is to still have addons control their own transpilation process, but -make them honour user preferences by default. - -There are three different scenarios for addons: - -#### The addon doesn't care about the transpilation process. -This is the most common common situation. Most addons are authored in ES6 and they don't -mess with the host app's configuration. -Those addons should just transpile their code user the host's apps settings. - -#### Addons that require experimental features -There are two options here. Either addons can unconditionally enable that feature only for their -tree, or it's the user responsability to enable that feature in order to use the addon, with -optionally the addon doing some feature detection to warn (not force) the user to enable that feature. - -By example, an addon that uses `async-await` which right now are only available in Chrome Canary -could either use the host app's configuration plus this feature or it could just assume the user -has enabled it and tell them to do so in the docs. - -#### Addons that add their custom babel plugins - -The number of addons that does this is even smaller, but one of them is nothing less than Ember Data, -which uses a babel-plugin to strip Heimdall's instrumentation from production builds. - -Since addons remain in control of their transpilation and just reuse the app's configuration, addons -can attach their own plugins. +make them honor the user's preferences by default. -#### How can addons be in charge of their own transpilation and yet honor user preferences? +The implementation is relatively straigtforward. Every addon receives a deep clone of the application's +configuration (available by example on `this.config.babel`), and `ember-cli-babel` must transpile +the addon using those options, which happen to be the options used in the container app. -Ember-cli should provide to each addon a deep clone of the configuration defined in the host app -(by example available in `this.options.babel`), and that config is the one used to transpile the addon. +Note that addons are still in control of the transpilation, they just happen to reuse the app's config +unless the addon author decides otherwise. -The addon will therefore honor the app's configuration by default, but it can also decide to add -custom plugins, enable specific features or just throw a warning message if the app's config -doesn't have required specific transformation enabled. +Addons that require custom plugins can still get the configuration and modify it, but since it is +a deep clone of the app's configuration, they can be sure that any change they make will be scoped +to that addon and will not affect other addons or the container app. -By modifying this clone, their changes will not affect the host app or other addons. +Note that addon authors _could_ enable optional plugins, like per example [**decorators**](https://github.com/martndemus/ember-font-awesome/blob/master/index.js#L13-L20). +However, since experimental features might become part of the ecmascript spec, this should be +generally discouraged. # How We Teach This @@ -81,9 +72,8 @@ or ember data will have to be updated. # Drawbacks -We give the users more control over the transpilation process at the expenses of some complexity -for addon authors that want to use experimental ES2017 features in their addons, leaving -up to them to give a good user experience. +Although this change *does not* require upgrading to BabelJS, it will be something to take into account +by whatever transition happens last. # Alternatives From 891f7eca96ba734064965f82c6aa00803aca383a Mon Sep 17 00:00:00 2001 From: Miguel Camba Date: Mon, 12 Dec 2016 15:26:12 +0000 Subject: [PATCH 8/9] Update 0000-control-transpilation.md --- active/0000-control-transpilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index 2a6c607..b5173e4 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -4,7 +4,7 @@ # Summary -Change how addon code is transpiled to it honors user preferences by default, but still +Change how addon code is transpiled so it honors user preferences by default, but still allow addons to be in control of the transpilation if they need to. # Motivation From 74a606c1e54ae7dfab129bfde6457b1e92749c96 Mon Sep 17 00:00:00 2001 From: Miguel Camba Date: Mon, 12 Dec 2016 15:27:42 +0000 Subject: [PATCH 9/9] Update 0000-control-transpilation.md --- active/0000-control-transpilation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/active/0000-control-transpilation.md b/active/0000-control-transpilation.md index b5173e4..c491529 100644 --- a/active/0000-control-transpilation.md +++ b/active/0000-control-transpilation.md @@ -16,7 +16,7 @@ Today that is done through `ember-cli-babel`, an addon that is in the default bl that the huge majority of apps use. This transpilation process has some sensible defaults that work for most people, but also allow -some use configuration for, by example, disable some transformations enabled by default or enable +some user configuration to, by example, disable some transformations enabled by default or enable some experimental ones. What is less known is that this configuration only affects the application code (the one in your app