From 6d064a9c1ff0f0651c183234db6c32383c27bc6c Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Thu, 15 Feb 2018 11:03:26 -0500 Subject: [PATCH 01/12] Deprecate Falling Back To Property Lookup --- ...0000-deprecate-property-lookup-fallback.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 text/0000-deprecate-property-lookup-fallback.md diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md new file mode 100644 index 0000000000..82e1eddc98 --- /dev/null +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -0,0 +1,86 @@ +- Start Date: 2-15-2018 +- RFC PR: +- Ember Issue: + +# Summary + +Deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates's backing component. This would be the default behavior in Glimmer Components. + +For example, given the following component class: + +```js +import Component from '@ember/component'; +export default Component.extends({ + init() { + super(...arguments); + this.set('greeting', 'Hello'); + } +}); +``` + +One would refer to the `greeting` property as such: + +```hbs +

{{this.greeting}}, Chad

+``` + +Ember will render "Hello, Chad". + +# Motivation + +Currently, the way to access properties on a components class is `{{greeting}}` from a template. This works because the component class is one of the objects we resolve against during the evaluation of the expression. + +The first problem with this approach is that the `{{greeting}}` syntax is ambiguous, as it could be referring to a local variable (block param), a helper with no arguments, a closed over component, or a property on the component class. + +This can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. + +Like [RFC#0276](https://github.com/emberjs/rfcs/blob/68812bf2d439c6bb77ad491e0159b371b68c5c35/text/0276-named-args.md) made argument usage explicit through the `@` prefix, the `this` prefix will resolve the ambiguity and greatly improve clarity, especially in big projects with a lot of files (and uses a lot of addons). + +As an aside, the ambiguity that causes confusion for human readers is also a problem for the compiler. While it is not the main goal of this proposal, resolving this ambiguity also helps the rendering system. Currently, the "runtime" template compiler has to perform a helper lookup for every `{{greeting}}` in each template. It will be able to skip this resolution process and perform other optimizations (such as reusing the internal [reference](https://github.com/glimmerjs/glimmer-vm/blob/master/guides/04-references.md) +object and caches) with this addition. + +Furthermore, by enforcing the `this` prefix tooling like the [Ember Language Server](https://github.com/emberwatch/ember-language-server) does not need to know about fallback resolution rules. This makes common features like ["Go To Definition"](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition) much easier to implement since we have semantics that mean "property on class". + +# Transition Path +The `{{this.foo}}` syntax has always been supported Handlebars and thus can be used in every version of Ember, however no guides or documentation promote its usage. While applications can start migrating today to this more explicit syntax, we can surface information about what properties on the class were accessed allowing developers to get a concise list of expressions that should be migrated. This can be surfaced because we are already disambiguate the syntax at runtime. + +# How We Teach This + +`{{this.foo}}` is the way to access the properties on the component class. This also aligns to property access in JavaScript. + +Since the `{{this.foo}}` syntax has worked in Ember.Component (which is the only kind of components available today) since the 1.0 series, we are not really in a rush to migrate the community (and the guides, etc) to using the new syntax. In the meantime, this could be viewed as a tool to improve clarity in templates. + +While we think writing {{this.foo}} would be a best practice for new code going forward, the community can migrate at its own pace one component at a time. However, once the fallback functionality is eventually removed this will result in a "Helper not found" error. + +We can also encourage the community to supplement this effort by wiring linting tools and code mods. + +## Syntax Breakdown +The follow is a breakdown of the different forms and what they mean. + +- `{{@foo}}` is an argument passed to the component +- `{{this.foo}}` is a property on the component class +- `{{#with this.foo as |foo|}} {{foo}} {{/with}}` the `{{foo}}` is a local +- `{{foo}}` is a helper + +# Drawbacks +The largest downside of this proposal is that it makes templates more verbose, causing developers to type a bit more. This will also create a decent amount of deprecation noise, although we feel like tools like [ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow) can help mitigate this. + +# Alternatives +This pattern of having programming model constructs to distinguish between of the backing class and arguments passed to the component is not unique to Ember. + +## What Other Frameworks Do +React has used `this.props` to talk about values passed to you and `this.state` to mean data owned by the backing component class since it was released. However, this approach of creating a specific object on the component class to mean "properties available to the template", would likely be even more an invasive change and goes against the mental model that the context for the template is the class. + +Vue requires enumeration of `props` passed to a component, but the values in the template suffer from the ambiguity that we are trying to solve. + +Angular relies heavily on the dependency injection e.g. `@Input` to enumerate the bindings that were passed to the component and relies heavily on TypeScript to hide or expose values to templating layer with `public` and `private` fields. Like Vue, Angular does not disambiguate. + +## Introduce Yet Another Sigil +We could introduce another sigil to remove ambiguity. This would address the concern about verbosity, however it is now another thing we would have to teach. + +## Do Nothing +I personally don't think this is an option, since the goal is to provide clarity for applications as they evolve over time and to provide a more consise mental model. + +# Unresolved questions +Soon... + From def91231cd64f07d7918642a078f05638a5da822 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Fri, 16 Feb 2018 15:09:24 -0500 Subject: [PATCH 02/12] Add example of fallback issue --- ...0000-deprecate-property-lookup-fallback.md | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 82e1eddc98..6d79c4cc66 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -32,7 +32,47 @@ Currently, the way to access properties on a components class is `{{greeting}}` The first problem with this approach is that the `{{greeting}}` syntax is ambiguous, as it could be referring to a local variable (block param), a helper with no arguments, a closed over component, or a property on the component class. -This can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. +## Exemplar +Consider the following example where the ambiguity can cause issues: + +You have a component class that looks like the following component and template: + +```js +import Component from '@ember/component'; +import computed from '@ember/computed'; + +export default Component.extend({ + formatName: computed('firstName', 'lastName', function() { + return `${this.firstName} ${this.lastName}`; + }); +}); +``` + +```hbs +

Hello {{formatName}}!

+``` + +Given `{ firstName: 'Chad', lastName: 'Hietala' }` Ember will render the following: + +```html +

Hello Chad Hietala!

+``` + +Now some time goes on and someone adds a `formatName` helper that looks like the following: + +```js +export default function formatName([firstName, lastName]) { + return `${this.firstName} ${this.lastName}`; +} +``` + +Due to the fact helpers take precedence over property lookups our `{{formatName}}` now resolves to a helper. When the helper runs it doesn't have any arguments so our template now renders the following: + +```html +

Hello !

+``` + +This can be a refactoring hazord and can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. Like [RFC#0276](https://github.com/emberjs/rfcs/blob/68812bf2d439c6bb77ad491e0159b371b68c5c35/text/0276-named-args.md) made argument usage explicit through the `@` prefix, the `this` prefix will resolve the ambiguity and greatly improve clarity, especially in big projects with a lot of files (and uses a lot of addons). @@ -44,6 +84,8 @@ Furthermore, by enforcing the `this` prefix tooling like the [Ember Language Ser # Transition Path The `{{this.foo}}` syntax has always been supported Handlebars and thus can be used in every version of Ember, however no guides or documentation promote its usage. While applications can start migrating today to this more explicit syntax, we can surface information about what properties on the class were accessed allowing developers to get a concise list of expressions that should be migrated. This can be surfaced because we are already disambiguate the syntax at runtime. +Using this information, we will also have the ability to create a codemod that will help migrate templates. + # How We Teach This `{{this.foo}}` is the way to access the properties on the component class. This also aligns to property access in JavaScript. @@ -52,8 +94,6 @@ Since the `{{this.foo}}` syntax has worked in Ember.Component (which is the only While we think writing {{this.foo}} would be a best practice for new code going forward, the community can migrate at its own pace one component at a time. However, once the fallback functionality is eventually removed this will result in a "Helper not found" error. -We can also encourage the community to supplement this effort by wiring linting tools and code mods. - ## Syntax Breakdown The follow is a breakdown of the different forms and what they mean. From dd6b35931d4f8416c246ee9b65cd70c3b4541f67 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Fri, 16 Feb 2018 15:24:30 -0500 Subject: [PATCH 03/12] Update 0000-deprecate-property-lookup-fallback.md --- text/0000-deprecate-property-lookup-fallback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 6d79c4cc66..32f84a133c 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -72,7 +72,7 @@ Due to the fact helpers take precedence over property lookups our `{{formatName}

Hello !

``` -This can be a refactoring hazord and can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. +This can be a refactoring hazard and can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. Like [RFC#0276](https://github.com/emberjs/rfcs/blob/68812bf2d439c6bb77ad491e0159b371b68c5c35/text/0276-named-args.md) made argument usage explicit through the `@` prefix, the `this` prefix will resolve the ambiguity and greatly improve clarity, especially in big projects with a lot of files (and uses a lot of addons). From b40deaa95e2377f8901082e3d9ab03a607c4197f Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Sat, 17 Feb 2018 16:21:03 +0000 Subject: [PATCH 04/12] Fix helper code sample --- text/0000-deprecate-property-lookup-fallback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 32f84a133c..62e741f62f 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -62,7 +62,7 @@ Now some time goes on and someone adds a `formatName` helper that looks like the ```js export default function formatName([firstName, lastName]) { - return `${this.firstName} ${this.lastName}`; + return `${firstName} ${lastName}`; } ``` From 555b5e8e878a4869e1ce06a663081873f65bcbd4 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Sat, 17 Feb 2018 16:36:55 +0000 Subject: [PATCH 05/12] Update 0000-deprecate-property-lookup-fallback.md --- ...0000-deprecate-property-lookup-fallback.md | 33 ++++++++++++------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 62e741f62f..f9247b8c64 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -4,7 +4,7 @@ # Summary -Deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates's backing component. This would be the default behavior in Glimmer Components. +Deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates' backing component. This would be the default behavior in Glimmer Components. For example, given the following component class: @@ -33,6 +33,7 @@ Currently, the way to access properties on a components class is `{{greeting}}` The first problem with this approach is that the `{{greeting}}` syntax is ambiguous, as it could be referring to a local variable (block param), a helper with no arguments, a closed over component, or a property on the component class. ## Exemplar + Consider the following example where the ambiguity can cause issues: You have a component class that looks like the following component and template: @@ -52,7 +53,7 @@ export default Component.extend({

Hello {{formatName}}!

``` -Given `{ firstName: 'Chad', lastName: 'Hietala' }` Ember will render the following: +Given `{ firstName: 'Chad', lastName: 'Hietala' }`, Ember will render the following: ```html

Hello Chad Hietala!

@@ -66,36 +67,38 @@ export default function formatName([firstName, lastName]) { } ``` -Due to the fact helpers take precedence over property lookups our `{{formatName}}` now resolves to a helper. When the helper runs it doesn't have any arguments so our template now renders the following: +Due to the fact that helpers take precedence over property lookups, our `{{formatName}}` now resolves to a helper. When the helper runs it doesn't have any arguments so our template now renders the following: ```html

Hello !

``` -This can be a refactoring hazard and can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first you need to scan the surrounding lines for block params with that name; next you check in the helpers folder to see it there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. +This can be a refactoring hazard and can often lead to confusion for readers of the template. Upon encountering `{{greeting}}` in a component's template, the reader has to check all of these places: first, you need to scan the surrounding lines for block params with that name; next, you check in the helpers folder to see if there is a helper with that name (it could also be coming from an addon!); finally, you check the component's JavaScript class to look for a (computed) property. Like [RFC#0276](https://github.com/emberjs/rfcs/blob/68812bf2d439c6bb77ad491e0159b371b68c5c35/text/0276-named-args.md) made argument usage explicit through the `@` prefix, the `this` prefix will resolve the ambiguity and greatly improve clarity, especially in big projects with a lot of files (and uses a lot of addons). As an aside, the ambiguity that causes confusion for human readers is also a problem for the compiler. While it is not the main goal of this proposal, resolving this ambiguity also helps the rendering system. Currently, the "runtime" template compiler has to perform a helper lookup for every `{{greeting}}` in each template. It will be able to skip this resolution process and perform other optimizations (such as reusing the internal [reference](https://github.com/glimmerjs/glimmer-vm/blob/master/guides/04-references.md) object and caches) with this addition. -Furthermore, by enforcing the `this` prefix tooling like the [Ember Language Server](https://github.com/emberwatch/ember-language-server) does not need to know about fallback resolution rules. This makes common features like ["Go To Definition"](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition) much easier to implement since we have semantics that mean "property on class". +Furthermore, by enforcing the `this` prefix, tooling like the [Ember Language Server](https://github.com/emberwatch/ember-language-server) does not need to know about fallback resolution rules. This makes common features like ["Go To Definition"](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition) much easier to implement since we have semantics that mean "property on class". # Transition Path -The `{{this.foo}}` syntax has always been supported Handlebars and thus can be used in every version of Ember, however no guides or documentation promote its usage. While applications can start migrating today to this more explicit syntax, we can surface information about what properties on the class were accessed allowing developers to get a concise list of expressions that should be migrated. This can be surfaced because we are already disambiguate the syntax at runtime. + +The `{{this.foo}}` syntax has always been supported Handlebars syntax and thus can be used in every version of Ember. However, no guides or documentation promote its usage. While applications can start migrating today to this more explicit syntax, we can surface information about what properties on the class were accessed allowing developers to get a concise list of expressions that should be migrated. This can be surfaced because we are already disambiguating the syntax at runtime. Using this information, we will also have the ability to create a codemod that will help migrate templates. # How We Teach This -`{{this.foo}}` is the way to access the properties on the component class. This also aligns to property access in JavaScript. +`{{this.foo}}` is the way to access the properties on the component class. This also aligns with property access in JavaScript. -Since the `{{this.foo}}` syntax has worked in Ember.Component (which is the only kind of components available today) since the 1.0 series, we are not really in a rush to migrate the community (and the guides, etc) to using the new syntax. In the meantime, this could be viewed as a tool to improve clarity in templates. +Since the `{{this.foo}}` syntax has worked in Ember.Component (which is the only kind of component available today) since the 1.0 series, we are not really in a rush to migrate the community (and the guides, etc) to using the new syntax. In the meantime, this could be viewed as a tool to improve clarity in templates. -While we think writing {{this.foo}} would be a best practice for new code going forward, the community can migrate at its own pace one component at a time. However, once the fallback functionality is eventually removed this will result in a "Helper not found" error. +While we think writing `{{this.foo}}` would be a best practice for new code going forward, the community can migrate at its own pace one component at a time. However, once the fallback functionality is eventually removed this will result in a "Helper not found" error. ## Syntax Breakdown -The follow is a breakdown of the different forms and what they mean. + +The follow is a breakdown of the different forms and what they mean: - `{{@foo}}` is an argument passed to the component - `{{this.foo}}` is a property on the component class @@ -103,12 +106,15 @@ The follow is a breakdown of the different forms and what they mean. - `{{foo}}` is a helper # Drawbacks + The largest downside of this proposal is that it makes templates more verbose, causing developers to type a bit more. This will also create a decent amount of deprecation noise, although we feel like tools like [ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow) can help mitigate this. # Alternatives + This pattern of having programming model constructs to distinguish between of the backing class and arguments passed to the component is not unique to Ember. ## What Other Frameworks Do + React has used `this.props` to talk about values passed to you and `this.state` to mean data owned by the backing component class since it was released. However, this approach of creating a specific object on the component class to mean "properties available to the template", would likely be even more an invasive change and goes against the mental model that the context for the template is the class. Vue requires enumeration of `props` passed to a component, but the values in the template suffer from the ambiguity that we are trying to solve. @@ -116,11 +122,14 @@ Vue requires enumeration of `props` passed to a component, but the values in the Angular relies heavily on the dependency injection e.g. `@Input` to enumerate the bindings that were passed to the component and relies heavily on TypeScript to hide or expose values to templating layer with `public` and `private` fields. Like Vue, Angular does not disambiguate. ## Introduce Yet Another Sigil + We could introduce another sigil to remove ambiguity. This would address the concern about verbosity, however it is now another thing we would have to teach. ## Do Nothing -I personally don't think this is an option, since the goal is to provide clarity for applications as they evolve over time and to provide a more consise mental model. + +I personally don't think this is an option, since the goal is to provide clarity for applications as they evolve over time and to provide a more concise mental model. # Unresolved questions -Soon... + +Soon… From ba2d102cde995a18b43155054b9b39a3d3cc5ebc Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Sat, 17 Feb 2018 14:05:41 -0500 Subject: [PATCH 06/12] Update 0000-deprecate-property-lookup-fallback.md --- text/0000-deprecate-property-lookup-fallback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index f9247b8c64..b4536a4abf 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -59,7 +59,7 @@ Given `{ firstName: 'Chad', lastName: 'Hietala' }`, Ember will render the follow

Hello Chad Hietala!

``` -Now some time goes on and someone adds a `formatName` helper that looks like the following: +Now some time goes on and someone adds a `formatName` helper at `app/helpers/fortmatName.js` that looks like the following: ```js export default function formatName([firstName, lastName]) { From 6d8a46dc55a90b20d89dbf305cf496f376a62f73 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Sat, 17 Feb 2018 14:06:42 -0500 Subject: [PATCH 07/12] Update 0000-deprecate-property-lookup-fallback.md --- text/0000-deprecate-property-lookup-fallback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index b4536a4abf..f04a5dd93d 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -111,7 +111,7 @@ The largest downside of this proposal is that it makes templates more verbose, c # Alternatives -This pattern of having programming model constructs to distinguish between of the backing class and arguments passed to the component is not unique to Ember. +This pattern of having programming model constructs to distinguish between the backing class and arguments passed to the component is not unique to Ember. ## What Other Frameworks Do From 5994c456a33748d589835bb5459df11eb0b2760f Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Sat, 17 Feb 2018 15:07:54 -0500 Subject: [PATCH 08/12] Mention codemod in Summary --- text/0000-deprecate-property-lookup-fallback.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index f04a5dd93d..fc9b525527 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -26,6 +26,8 @@ One would refer to the `greeting` property as such: Ember will render "Hello, Chad". +To make this deprecation tractable, we will provide a codemod for migrating templates. + # Motivation Currently, the way to access properties on a components class is `{{greeting}}` from a template. This works because the component class is one of the objects we resolve against during the evaluation of the expression. From 73f158406f1ea5a24b3487b3bb46f277966e0378 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Sat, 17 Feb 2018 15:24:15 -0500 Subject: [PATCH 09/12] Change Resolution Order --- text/0000-deprecate-property-lookup-fallback.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index fc9b525527..85dba97533 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -127,11 +127,14 @@ Angular relies heavily on the dependency injection e.g. `@Input` to enumerate th We could introduce another sigil to remove ambiguity. This would address the concern about verbosity, however it is now another thing we would have to teach. +## Change Resolution Order + +The other option is to reverse the resolution order to prefer properties over helpers. However this has the reverse problem as described in the exemplar. + ## Do Nothing I personally don't think this is an option, since the goal is to provide clarity for applications as they evolve over time and to provide a more concise mental model. # Unresolved questions - -Soon… +TBD From 515ceb3ef1afff321660df834af68c8a54442a84 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Fri, 1 Jun 2018 17:28:11 -0400 Subject: [PATCH 10/12] Update transition plan This updates the transition section to explain the slow roll out all the way to it's removal in 4.4.0. --- ...0000-deprecate-property-lookup-fallback.md | 28 +++++++++++++++++-- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 85dba97533..27ca5fe44a 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -4,7 +4,7 @@ # Summary -Deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates' backing component. This would be the default behavior in Glimmer Components. +Beging the transition to deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates' backing component. This would be the default behavior in Glimmer Components. For example, given the following component class: @@ -86,9 +86,31 @@ Furthermore, by enforcing the `this` prefix, tooling like the [Ember Language Se # Transition Path -The `{{this.foo}}` syntax has always been supported Handlebars syntax and thus can be used in every version of Ember. However, no guides or documentation promote its usage. While applications can start migrating today to this more explicit syntax, we can surface information about what properties on the class were accessed allowing developers to get a concise list of expressions that should be migrated. This can be surfaced because we are already disambiguating the syntax at runtime. +We intend this to be a _very slow_ process as we understand it is a large change. Because of this we will be doing a phased rollout to help guide people in transtion. Below is an outline of how we plan to roll this change out. -Using this information, we will also have the ability to create a codemod that will help migrate templates. +**Phase 1:** +- Add [template lint rule](https://github.com/ember-template-lint/ember-template-lint/pull/392) to [ember-template-lint](https://github.com/ember-template-lint/ember-template-lint) as an **opt-in** rule +- Document the [codemod infrastructure](https://github.com/dyfactor/dyfactor) and [codemod](https://github.com/dyfactor/dyfactor-plugin-disambiguate-locals). Make it available for early adopters +- Start updating docs to use `this.` + +**Phase 2:** +- Add the lint rule by default _in the apps_ `.template-lintrc.js` +- Complete doc migration to use `this.` + +**Phase 3:** +- Enable the lint rule by default in the `recommended` config + +**Phase 4:** +- Introduce deprecation **app only** fallbacks + +**Phase 5:** +- Introduce deprecation for **any** fallbacks + +**Phase 6:** +- Rev major to 4.0.0 + +**Phase 7:** +- Remove fallback functionality post 4.3.0 LTS # How We Teach This From cb6cda650553bb404056d53dca1d3e8045b67d6f Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Fri, 1 Jun 2018 18:07:54 -0400 Subject: [PATCH 11/12] sp --- text/0000-deprecate-property-lookup-fallback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index 27ca5fe44a..acfcb90a72 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -4,7 +4,7 @@ # Summary -Beging the transition to deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates' backing component. This would be the default behavior in Glimmer Components. +Beginning the transition to deprecate the fallback behavior of resolving `{{foo}}` by requiring the usage of `{{this.foo}}` as syntax to refer to properties of the templates' backing component. This would be the default behavior in Glimmer Components. For example, given the following component class: From d44e0bd0dac1aa636f5c2e493cbbda302a953893 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Sat, 2 Jun 2018 23:23:31 -0400 Subject: [PATCH 12/12] Update versions and add assert in 4.0 --- text/0000-deprecate-property-lookup-fallback.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-deprecate-property-lookup-fallback.md b/text/0000-deprecate-property-lookup-fallback.md index acfcb90a72..227162bfd6 100644 --- a/text/0000-deprecate-property-lookup-fallback.md +++ b/text/0000-deprecate-property-lookup-fallback.md @@ -108,9 +108,10 @@ We intend this to be a _very slow_ process as we understand it is a large change **Phase 6:** - Rev major to 4.0.0 +- Add assert for fallback behavior **Phase 7:** -- Remove fallback functionality post 4.3.0 LTS +- Remove fallback functionality in 4.5, post 4.4.0 LTS # How We Teach This