From 980b0e690bad4ca320874ba0ac5383f6f2dd1c95 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Wed, 19 Jul 2017 23:02:17 +0200 Subject: [PATCH 01/18] Ember.String deprecation RFC --- text/0000-deprecation-ember-string.md | 62 +++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 text/0000-deprecation-ember-string.md diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md new file mode 100644 index 0000000000..44bcc00faf --- /dev/null +++ b/text/0000-deprecation-ember-string.md @@ -0,0 +1,62 @@ +- Start Date: 2017-07-14 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Summary + +This PR proposes the deprecation of `Ember.String`. The following methods will be moved to an addon: + +- `camelize` +- `capitalize` +- `classify` +- `dasherize` +- `decamelize` +- `fmt` +- `loc` +- `underscore` +- `w` + +The remaining methods (`htmlSafe` and `isHTMLSafe`) will be moved to `@ember/component`. + +In both cases, the String prototype won't be extended anymore. + +# Motivation + +`Ember.String` was introduced long ago, even before 1.0 was released. It was a time without the current ecosystem of addons. There were no ES6 modules, no Ember CLI and no Ember addons. Global mode was the way to go and prototypes of classes like `String`, `Array` and `Function` were being extended. + +A lot of nice-to-have functionality was added at that time but now Ember is lifting weight. These functions belong in an addon, where it can be maintained and evolve without being tied to the core of the framework. + +Also, this would let people swap the function for similar implementations but different behaviour in edge cases. + +Once most of the methods are moved to an addon and `String` is no longer being extended, makes more sense to move `htmlSafe` and `isHTMLSafe` methods to the component layer. + + +# Transition Path + +Most methods will be extracted to an addon and will show a deprecation message when used from `Ember.String`. This way, if someone wants to use them, they just need to install an addon. + +For the last two, similar approach but moving them to the `@ember/component` module. + +# How We Teach This + +Ember guides' section on _disabling prototype extension_ would need to remove references to these methods. `camelize` is also used in the services tutorial. + +Main usage of these functions are in blueprints or connecting to APIs where converting the type of case of keys was needed. It is also used in Ember Data. + +Furthermore, when people have moved to the new shims, moving to an addon would be as easy as to change the import path. + +For `htmlSafe` and `isHTMLSafe`, the move is easier since the methods are easier related to components than to strings. + +In any case, a basic Ember Watson recipe would be easy to provide. + +# Drawbacks + +A lot of addons that deal with names depend on this behaviour, so they will need to install the addon. Also, Ember Data and some external serializers require these functions. + +`htmlSafe` and `isHTMLSafe` would need to change packages as well, thus the reason to try and provide an Ember Watson recipe. + +# Alternatives + +Leave things as they are. + +# Unresolved questions From 77f730583361a2e69702c3e320fb9cd593809945 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Mon, 7 Aug 2017 01:53:45 +0200 Subject: [PATCH 02/18] Update on RFC Update on RFC based on feedback --- text/0000-deprecation-ember-string.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 44bcc00faf..6adf31989c 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,7 +4,7 @@ # Summary -This PR proposes the deprecation of `Ember.String`. The following methods will be moved to an addon: +This PR proposes the deprecation of extending `String` with the methods in `Ember.String` and accessing those directly. Furthermore, the following methods will be moved to a new `ember-string` addon. - `camelize` - `capitalize` @@ -18,13 +18,11 @@ This PR proposes the deprecation of `Ember.String`. The following methods will b The remaining methods (`htmlSafe` and `isHTMLSafe`) will be moved to `@ember/component`. -In both cases, the String prototype won't be extended anymore. - # Motivation `Ember.String` was introduced long ago, even before 1.0 was released. It was a time without the current ecosystem of addons. There were no ES6 modules, no Ember CLI and no Ember addons. Global mode was the way to go and prototypes of classes like `String`, `Array` and `Function` were being extended. -A lot of nice-to-have functionality was added at that time but now Ember is lifting weight. These functions belong in an addon, where it can be maintained and evolve without being tied to the core of the framework. +A lot of nice-to-have functionality was added at that time but now Ember has a better ecosystem. These functions belong in an addon, where it can be maintained and evolve without being tied to the core of the framework. Also, this would let people swap the function for similar implementations but different behaviour in edge cases. @@ -43,8 +41,6 @@ Ember guides' section on _disabling prototype extension_ would need to remove re Main usage of these functions are in blueprints or connecting to APIs where converting the type of case of keys was needed. It is also used in Ember Data. -Furthermore, when people have moved to the new shims, moving to an addon would be as easy as to change the import path. - For `htmlSafe` and `isHTMLSafe`, the move is easier since the methods are easier related to components than to strings. In any case, a basic Ember Watson recipe would be easy to provide. @@ -53,7 +49,7 @@ In any case, a basic Ember Watson recipe would be easy to provide. A lot of addons that deal with names depend on this behaviour, so they will need to install the addon. Also, Ember Data and some external serializers require these functions. -`htmlSafe` and `isHTMLSafe` would need to change packages as well, thus the reason to try and provide an Ember Watson recipe. +`htmlSafe` and `isHTMLSafe` would need to change packages, thus the reason to try and provide an Ember Watson recipe. # Alternatives From dcadbc1c3a742c5649ec8972d1d083e9cd727486 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Thu, 10 Aug 2017 19:05:39 +0200 Subject: [PATCH 03/18] Fix addon name --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 6adf31989c..0fae700914 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,7 +4,7 @@ # Summary -This PR proposes the deprecation of extending `String` with the methods in `Ember.String` and accessing those directly. Furthermore, the following methods will be moved to a new `ember-string` addon. +This PR proposes the deprecation of extending `String` with the methods in `Ember.String` and accessing those directly. Furthermore, the following methods will be moved to a new `@ember/string` addon. - `camelize` - `capitalize` From 0cf1e6d5fd6daafc71fdee751c1846c6c0d3744b Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 22 Aug 2017 18:58:10 +0100 Subject: [PATCH 04/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 0fae700914..59f03d05d6 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,30 +4,15 @@ # Summary -This PR proposes the deprecation of extending `String` with the methods in `Ember.String` and accessing those directly. Furthermore, the following methods will be moved to a new `@ember/string` addon. - -- `camelize` -- `capitalize` -- `classify` -- `dasherize` -- `decamelize` -- `fmt` -- `loc` -- `underscore` -- `w` - -The remaining methods (`htmlSafe` and `isHTMLSafe`) will be moved to `@ember/component`. +This RFC proposes to deprecate the prototype extensions done by `Ember.String` and the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/component`. # Motivation -`Ember.String` was introduced long ago, even before 1.0 was released. It was a time without the current ecosystem of addons. There were no ES6 modules, no Ember CLI and no Ember addons. Global mode was the way to go and prototypes of classes like `String`, `Array` and `Function` were being extended. - -A lot of nice-to-have functionality was added at that time but now Ember has a better ecosystem. These functions belong in an addon, where it can be maintained and evolve without being tied to the core of the framework. - -Also, this would let people swap the function for similar implementations but different behaviour in edge cases. +Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. -Once most of the methods are moved to an addon and `String` is no longer being extended, makes more sense to move `htmlSafe` and `isHTMLSafe` methods to the component layer. +With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. +In the specific case of `Ember.String`, our goal is that users that need it will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). # Transition Path From 2c11102d8886842010b8e37038f51c746e09a0b1 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Wed, 23 Aug 2017 08:35:17 +0100 Subject: [PATCH 05/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 59f03d05d6..bf8924d11d 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,7 +4,7 @@ # Summary -This RFC proposes to deprecate the prototype extensions done by `Ember.String` and the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/component`. +This RFC proposes to deprecate the prototype extensions done by `Ember.String`, deprecate the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/component`. # Motivation From ff9b1903e709a7bd6ecb980a6de9b2d98ae298c2 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Wed, 23 Aug 2017 09:20:35 +0100 Subject: [PATCH 06/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 42 +++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index bf8924d11d..2b879cef01 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -12,13 +12,49 @@ Much of the public API of Ember was designed and published some time ago, when t With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. -In the specific case of `Ember.String`, our goal is that users that need it will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). +In the specific case of `Ember.String`, our goal is that users that need who these utility functions will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). # Transition Path -Most methods will be extracted to an addon and will show a deprecation message when used from `Ember.String`. This way, if someone wants to use them, they just need to install an addon. +It is important to understand that the transition path will be done in the context of the new modules API defined in RFC #176, which is scheduled to land in 2.16. +As this will likely be first of many packages to be extracted from the Ember source, the transition path arrived on needs to be clear and user-friendly. -For the last two, similar approach but moving them to the `@ember/component` module. +## What is happening for framework developers? + +The order of operations will be as follows: + +* Move `htmlSafe` and `isHTMLSafe` to `@ember/component` + * Update https://github.com/ember-cli/ember-rfc176-data +* Create an `@ember/string` package with the remaining public API +* Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning +* Make `ember-cli-babel` aware of the `@ember/string` package so it tells `babel-plugin-ember-modules-api-polyfill` not to convert those imports to the global `Ember` namespace +* Update usages in Ember and Ember Data codebases so that the projects do not trigger deprecations +* Deprecate `Ember.String` + * Write deprecation guide which mentions minimum version of `ember-cli-babel`, and how/when to use `@ember/string` and `ember-string-prototype-extensions` packages +* Deprecate `loc` in `@ember/string` + +## What is happening for framework users? + +If you are using `Ember.String.loc`, you will be instructed to move to a dedicated localization solution, as this method will be completely deprecated. + +If you are using `Ember.String.htmlSafe` or `Ember.String.isHTMLSafe`, you will be instructed to run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod) and it will update to the correct imports from the `@ember/component` package. + +If you are using one of the other `Ember.String` methods, like `Ember.String.dasherize`, you will receive a deprecation warning to inform you that you should run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod), update `ember-cli-babel` to a specific minor version, and add `@ember/string` to your application's or addon's dependencies. + +If you are using the `String` prototype extensions, like `"myString".dasherize()`, on top of the previous instructions you will be instructed to install `ember-string-prototype-extensions` in case updating the code to `dasherize("myString")` is not trivial. + +## Timeline + +* Deprecations are introduced - Ember 2.x + * `String` protoype extensions are deprecated + * `Ember.String` functions are deprecated + * `loc` is completely deprecated +* Transition packages are introduced - Ember 2.x + * `@ember/string`, which replaced `Ember.String` + * `ember-string-prototype-extensions`, which brings `String` prototype extensions back +* Deprecations are removed - Ember 3.x, `@ember/string` 2.x + * New major version of Ember is released + * New major version of `@ember/string` is released # How We Teach This From f467aa1b861baaecf7a72bc80d5be50ce4c7ad6f Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Wed, 23 Aug 2017 10:41:05 +0100 Subject: [PATCH 07/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 39 +++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 2b879cef01..2156931273 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -41,7 +41,7 @@ If you are using `Ember.String.htmlSafe` or `Ember.String.isHTMLSafe`, you will If you are using one of the other `Ember.String` methods, like `Ember.String.dasherize`, you will receive a deprecation warning to inform you that you should run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod), update `ember-cli-babel` to a specific minor version, and add `@ember/string` to your application's or addon's dependencies. -If you are using the `String` prototype extensions, like `"myString".dasherize()`, on top of the previous instructions you will be instructed to install `ember-string-prototype-extensions` in case updating the code to `dasherize("myString")` is not trivial. +If you are using the `String` prototype extensions, like `'myString'.dasherize()`, on top of the previous instructions you will be instructed to install `ember-string-prototype-extensions` in case updating the code to `dasherize('myString')` is not trivial. ## Timeline @@ -58,13 +58,40 @@ If you are using the `String` prototype extensions, like `"myString".dasherize() # How We Teach This -Ember guides' section on _disabling prototype extension_ would need to remove references to these methods. `camelize` is also used in the services tutorial. +## Official code bases and documentation -Main usage of these functions are in blueprints or connecting to APIs where converting the type of case of keys was needed. It is also used in Ember Data. +The official documentation–website, Guides, API documentation–should be updated not to use `String` prototype extensions. +This documentation should already use the new modules API from an effort to update it for Ember 2.16. -For `htmlSafe` and `isHTMLSafe`, the move is easier since the methods are easier related to components than to strings. +The Guides section on _disabling prototype extension_ will need to be updated when `String` prototype extensions are removed from Ember. -In any case, a basic Ember Watson recipe would be easy to provide. +Resources owned by the Ember teams, such and Ember and Ember Data code bases, the Super Rentals repository, or the builds app for the website, will be updated accordingly. + +## `Ember.String.htmlSafe` and `Ember.String.isHTMLSafe` + +The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/component` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. + +## `Ember.String.loc` and `import { loc } from '@ember/string';`, `Ember.String` to `@ember/string`, `String` prototype extensions + +An entry to the [Deprecation Guides](https://emberjs.com/deprecations/) will be added outlining the different recommended transition strategies. + +### `Ember.String.loc`, `import { loc } from '@ember/string';` + +As this function is deprecated, users will be recommended to use a [dedicated localization solution](https://emberobserver.com/categories/internationalization). + +### `Ember.String` to `@ember/string` + +The way that `@ember`-scoped modules will work in 2.16 is that `ember-cli-babel` will convert something like `import { dasherize } from '@ember/string';` to `import Ember from 'Ember'; const dasherize = Ember.String.dasherize;`. +What this means is that `import { dasherize } from '@ember/string';` will trigger a deprecation if you do not have the `@ember/string` package in your dependencies. + +To address the above deprecation you will need to update `ember-cli-babel` to a a specific minor version or higher, to make sure it has the logic to detect `@ember/string`. The specific minor version will be known at the time the deprecation guide is written. +You will also need to add `@ember/string` to your application's development dependencies, or your addon's dependencies. + +### `String` prototype extensions + +If you are using `'myString'.dasherize()` or one of the other functions added to `String`, you will be instructed to replace that usage with `import { dasherize } from '@ember/string'; dasherize('myString')`, in addition to the changes on the previous section. + +In case your code base is complicated enough that migrating all these usages at the same time is not convenient, you will be able to add `ember-string-prototype-extensions` to your dependencies, which will bring back extensions, without deprecations. # Drawbacks @@ -72,6 +99,8 @@ A lot of addons that deal with names depend on this behaviour, so they will need `htmlSafe` and `isHTMLSafe` would need to change packages, thus the reason to try and provide an Ember Watson recipe. +Another side-effect of this change is that certain users might be shipping duplicated code between `Ember.String` and `@ember/string`, but it is a necessary stepping stone and might be able to be addressed via svelting. + # Alternatives Leave things as they are. From ecd06abf8a342c79de309f53db6f2a33d04f0877 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Wed, 23 Aug 2017 11:51:31 +0200 Subject: [PATCH 08/18] Minor fixes --- text/0000-deprecation-ember-string.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 2156931273..fd0f9c2f87 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -23,15 +23,15 @@ As this will likely be first of many packages to be extracted from the Ember sou The order of operations will be as follows: -* Move `htmlSafe` and `isHTMLSafe` to `@ember/component` - * Update https://github.com/ember-cli/ember-rfc176-data -* Create an `@ember/string` package with the remaining public API -* Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning -* Make `ember-cli-babel` aware of the `@ember/string` package so it tells `babel-plugin-ember-modules-api-polyfill` not to convert those imports to the global `Ember` namespace -* Update usages in Ember and Ember Data codebases so that the projects do not trigger deprecations -* Deprecate `Ember.String` - * Write deprecation guide which mentions minimum version of `ember-cli-babel`, and how/when to use `@ember/string` and `ember-string-prototype-extensions` packages -* Deprecate `loc` in `@ember/string` +1. Move `htmlSafe` and `isHTMLSafe` to `@ember/component` + * Update https://github.com/ember-cli/ember-rfc176-data +2. Create an `@ember/string` package with the remaining public API +3. Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning +4. Make `ember-cli-babel` aware of the `@ember/string` package so it tells `babel-plugin-ember-modules-api-polyfill` not to convert those imports to the global `Ember` namespace +5. Update usages in Ember and Ember Data codebases so that the projects do not trigger deprecations +6. Deprecate `Ember.String` + * Write deprecation guide which mentions minimum version of `ember-cli-babel`, and how/when to use `@ember/string` and `ember-string-prototype-extensions` packages +7. Deprecate `loc` in `@ember/string` ## What is happening for framework users? @@ -60,7 +60,7 @@ If you are using the `String` prototype extensions, like `'myString'.dasherize() ## Official code bases and documentation -The official documentation–website, Guides, API documentation–should be updated not to use `String` prototype extensions. +The official documentation –website, Guides, API documentation– should be updated not to use `String` prototype extensions. This documentation should already use the new modules API from an effort to update it for Ember 2.16. The Guides section on _disabling prototype extension_ will need to be updated when `String` prototype extensions are removed from Ember. From 51dfe488dd147f8a5db5f3831a44c65988918358 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Thu, 31 Aug 2017 15:57:30 +0100 Subject: [PATCH 09/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index fd0f9c2f87..38b2acdc4e 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -1,5 +1,5 @@ - Start Date: 2017-07-14 -- RFC PR: (leave this empty) +- RFC PR: https://github.com/emberjs/rfcs/pull/236 - Ember Issue: (leave this empty) # Summary From 575aa50a7a879b34cd554d84293ebec523d23b09 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Sat, 2 Sep 2017 01:04:59 +0100 Subject: [PATCH 10/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 38b2acdc4e..ac3ad51f64 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -1,6 +1,6 @@ - Start Date: 2017-07-14 - RFC PR: https://github.com/emberjs/rfcs/pull/236 -- Ember Issue: (leave this empty) +- Ember Issue: https://github.com/emberjs/ember.js/issues/15624 # Summary From 4d2f23b8fca555cffe24a4f34843b8e4772aafc1 Mon Sep 17 00:00:00 2001 From: Julien Palmas Date: Thu, 7 Sep 2017 09:14:47 +0200 Subject: [PATCH 11/18] Update 0000-deprecation-ember-string.md typo --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index ac3ad51f64..0754679013 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -8,7 +8,7 @@ This RFC proposes to deprecate the prototype extensions done by `Ember.String`, # Motivation -Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. +Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. From a09d5f0ef911a8d5d14e3a6b58eaf6d322d3187f Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Fri, 15 Sep 2017 10:41:02 +0100 Subject: [PATCH 12/18] Update 0000-deprecation-ember-string.md (#2) * Update 0000-deprecation-ember-string.md * Update 0000-deprecation-ember-string.md * Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 0754679013..b8dd533592 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -10,10 +10,22 @@ This RFC proposes to deprecate the prototype extensions done by `Ember.String`, Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. -With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. +With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce and reorganize the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. In the specific case of `Ember.String`, our goal is that users that need who these utility functions will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). +To achieve the above goal we will move the `isHTMLSafe`/`htmlSafe` pair into a new package, deprecate `String.prototype` extensions, and deprecate the utility functions under the `Ember.String` namespace. + +Thehe ["Organize by Mental Model"](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md#organize-by-mental-model) section of RFC #176 mentions the concept of chunking. In the current setup, `isHTMLSafe`/`htmlSafe` make sense in the `Ember.String` namespace because they operate on strings, and they are available on the prototype, `"myString".htmlSafe()`. +However, once prototype extensions are removed, it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`, but are instead a templating concern. +For this reason, we are moving them to `@ember/templating`. + +Extending native prototypes, like we do for `String` with `"myString".dasherize()` and the rest of the API, has been falling out of favour more as time goes by. +While the tradeoff might have been positive at the beginning, as it allowed users access to a richer API, prototype extensions blur the line between what is the framework and what is the language in a way that is not benefitial in the current module-driven and package-rich ecosystem. + +Relatedly, deprecating `Ember.String` and requiring `@ember/string` as a dependency allows Ember to provide a leaner default core to all users, as well as iterate faster on the `@ember/string` package if desired. +Doing this will also open a path to extract more packages in the future. + # Transition Path It is important to understand that the transition path will be done in the context of the new modules API defined in RFC #176, which is scheduled to land in 2.16. @@ -23,7 +35,7 @@ As this will likely be first of many packages to be extracted from the Ember sou The order of operations will be as follows: -1. Move `htmlSafe` and `isHTMLSafe` to `@ember/component` +1. Move `htmlSafe` and `isHTMLSafe` to `@ember/templating` * Update https://github.com/ember-cli/ember-rfc176-data 2. Create an `@ember/string` package with the remaining public API 3. Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning @@ -49,6 +61,7 @@ If you are using the `String` prototype extensions, like `'myString'.dasherize() * `String` protoype extensions are deprecated * `Ember.String` functions are deprecated * `loc` is completely deprecated + * `isHTMLSafe` and `htmlSafe` are moved to `@ember/templating` * Transition packages are introduced - Ember 2.x * `@ember/string`, which replaced `Ember.String` * `ember-string-prototype-extensions`, which brings `String` prototype extensions back @@ -69,7 +82,7 @@ Resources owned by the Ember teams, such and Ember and Ember Data code bases, th ## `Ember.String.htmlSafe` and `Ember.String.isHTMLSafe` -The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/component` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. +The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/templating` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. ## `Ember.String.loc` and `import { loc } from '@ember/string';`, `Ember.String` to `@ember/string`, `String` prototype extensions @@ -106,3 +119,5 @@ Another side-effect of this change is that certain users might be shipping dupli Leave things as they are. # Unresolved questions + +None. From 8a1eab07045be78b40d77dc7b3021eb1d675e7c9 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Fri, 15 Sep 2017 10:42:22 +0100 Subject: [PATCH 13/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index b8dd533592..4e8c7788a1 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,7 +4,7 @@ # Summary -This RFC proposes to deprecate the prototype extensions done by `Ember.String`, deprecate the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/component`. +This RFC proposes to deprecate the prototype extensions done by `Ember.String`, deprecate the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/templating`. # Motivation From 762c9f8cc88e7a953cfcc7d90dd973020bb448b5 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Fri, 15 Sep 2017 10:44:43 +0100 Subject: [PATCH 14/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 4e8c7788a1..e081914253 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -16,9 +16,8 @@ In the specific case of `Ember.String`, our goal is that users that need who the To achieve the above goal we will move the `isHTMLSafe`/`htmlSafe` pair into a new package, deprecate `String.prototype` extensions, and deprecate the utility functions under the `Ember.String` namespace. -Thehe ["Organize by Mental Model"](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md#organize-by-mental-model) section of RFC #176 mentions the concept of chunking. In the current setup, `isHTMLSafe`/`htmlSafe` make sense in the `Ember.String` namespace because they operate on strings, and they are available on the prototype, `"myString".htmlSafe()`. -However, once prototype extensions are removed, it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`, but are instead a templating concern. -For this reason, we are moving them to `@ember/templating`. +The ["Organize by Mental Model"](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md#organize-by-mental-model) section of RFC #176 mentions the concept of chunking. In the current setup, `isHTMLSafe`/`htmlSafe` make sense in the `Ember.String` namespace because they operate on strings, and they are available on the prototype, `"myString".htmlSafe()`. +However, once prototype extensions are removed it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`. They are instead a way for the user to communicate to the templating engine that this string should be safe to render. For this reason, moving to `@ember/templating` seems appropriate. Extending native prototypes, like we do for `String` with `"myString".dasherize()` and the rest of the API, has been falling out of favour more as time goes by. While the tradeoff might have been positive at the beginning, as it allowed users access to a richer API, prototype extensions blur the line between what is the framework and what is the language in a way that is not benefitial in the current module-driven and package-rich ecosystem. From 84c513115d287166a2984122c662334d6beae5c2 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Fri, 15 Sep 2017 11:57:22 +0200 Subject: [PATCH 15/18] Fix minor wording --- text/0000-deprecation-ember-string.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index e081914253..89bcc37fc2 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -8,11 +8,11 @@ This RFC proposes to deprecate the prototype extensions done by `Ember.String`, # Motivation -Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. +Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI and the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce and reorganize the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. -In the specific case of `Ember.String`, our goal is that users that need who these utility functions will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). +In the specific case of `Ember.String`, our goal is that users that need these utility functions will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). To achieve the above goal we will move the `isHTMLSafe`/`htmlSafe` pair into a new package, deprecate `String.prototype` extensions, and deprecate the utility functions under the `Ember.String` namespace. From 138ae8c46baebaccf23dfbf41484494797d66c05 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Fri, 15 Sep 2017 17:07:33 +0100 Subject: [PATCH 16/18] Update 0000-deprecation-ember-string.md --- text/0000-deprecation-ember-string.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 89bcc37fc2..25745046dc 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -4,7 +4,7 @@ # Summary -This RFC proposes to deprecate the prototype extensions done by `Ember.String`, deprecate the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/templating`. +This RFC proposes to deprecate the prototype extensions done by `Ember.String`, deprecate the `loc` method, and moving `htmlSafe` and `isHTMLSafe` to `@ember/template`. # Motivation @@ -17,7 +17,7 @@ In the specific case of `Ember.String`, our goal is that users that need these u To achieve the above goal we will move the `isHTMLSafe`/`htmlSafe` pair into a new package, deprecate `String.prototype` extensions, and deprecate the utility functions under the `Ember.String` namespace. The ["Organize by Mental Model"](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md#organize-by-mental-model) section of RFC #176 mentions the concept of chunking. In the current setup, `isHTMLSafe`/`htmlSafe` make sense in the `Ember.String` namespace because they operate on strings, and they are available on the prototype, `"myString".htmlSafe()`. -However, once prototype extensions are removed it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`. They are instead a way for the user to communicate to the templating engine that this string should be safe to render. For this reason, moving to `@ember/templating` seems appropriate. +However, once prototype extensions are removed it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`. They are instead a way for the user to communicate to the templating engine that this string should be safe to render. For this reason, moving to `@ember/template` seems appropriate. Extending native prototypes, like we do for `String` with `"myString".dasherize()` and the rest of the API, has been falling out of favour more as time goes by. While the tradeoff might have been positive at the beginning, as it allowed users access to a richer API, prototype extensions blur the line between what is the framework and what is the language in a way that is not benefitial in the current module-driven and package-rich ecosystem. @@ -34,7 +34,7 @@ As this will likely be first of many packages to be extracted from the Ember sou The order of operations will be as follows: -1. Move `htmlSafe` and `isHTMLSafe` to `@ember/templating` +1. Move `htmlSafe` and `isHTMLSafe` to `@ember/template` * Update https://github.com/ember-cli/ember-rfc176-data 2. Create an `@ember/string` package with the remaining public API 3. Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning @@ -60,7 +60,7 @@ If you are using the `String` prototype extensions, like `'myString'.dasherize() * `String` protoype extensions are deprecated * `Ember.String` functions are deprecated * `loc` is completely deprecated - * `isHTMLSafe` and `htmlSafe` are moved to `@ember/templating` + * `isHTMLSafe` and `htmlSafe` are moved to `@ember/template` * Transition packages are introduced - Ember 2.x * `@ember/string`, which replaced `Ember.String` * `ember-string-prototype-extensions`, which brings `String` prototype extensions back @@ -81,7 +81,7 @@ Resources owned by the Ember teams, such and Ember and Ember Data code bases, th ## `Ember.String.htmlSafe` and `Ember.String.isHTMLSafe` -The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/templating` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. +The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/template` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. ## `Ember.String.loc` and `import { loc } from '@ember/string';`, `Ember.String` to `@ember/string`, `String` prototype extensions From 06d4761815f4e8bddcc85441189a8df223a35605 Mon Sep 17 00:00:00 2001 From: Sergio Arbeo Date: Tue, 19 Sep 2017 13:25:59 +0200 Subject: [PATCH 17/18] Remove last appearance of @ember/component --- text/0000-deprecation-ember-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index 25745046dc..6710d35da5 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -48,7 +48,7 @@ The order of operations will be as follows: If you are using `Ember.String.loc`, you will be instructed to move to a dedicated localization solution, as this method will be completely deprecated. -If you are using `Ember.String.htmlSafe` or `Ember.String.isHTMLSafe`, you will be instructed to run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod) and it will update to the correct imports from the `@ember/component` package. +If you are using `Ember.String.htmlSafe` or `Ember.String.isHTMLSafe`, you will be instructed to run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod) and it will update to the correct imports from the `@ember/template` package. If you are using one of the other `Ember.String` methods, like `Ember.String.dasherize`, you will receive a deprecation warning to inform you that you should run the [`ember-modules-codemod`](https://github.com/ember-cli/ember-modules-codemod), update `ember-cli-babel` to a specific minor version, and add `@ember/string` to your application's or addon's dependencies. From c1aea6b2a9f8d0109817cf2ef742201925d30263 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 26 Sep 2017 09:20:48 +0100 Subject: [PATCH 18/18] rename RFC file --- ...precation-ember-string.md => 0236-deprecation-ember-string.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0000-deprecation-ember-string.md => 0236-deprecation-ember-string.md} (100%) diff --git a/text/0000-deprecation-ember-string.md b/text/0236-deprecation-ember-string.md similarity index 100% rename from text/0000-deprecation-ember-string.md rename to text/0236-deprecation-ember-string.md