From e7a13538a5c1729b417756e9840f9a90202f2fb2 Mon Sep 17 00:00:00 2001 From: Godfrey Chan Date: Wed, 6 Jan 2021 01:34:00 -0800 Subject: [PATCH 1/2] Deprecate `` Component Positional Arguments --- ...-deprecate-link-to-positional-arguments.md | 178 ++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 text/0698-deprecate-link-to-positional-arguments.md diff --git a/text/0698-deprecate-link-to-positional-arguments.md b/text/0698-deprecate-link-to-positional-arguments.md new file mode 100644 index 0000000000..e1b6ae7202 --- /dev/null +++ b/text/0698-deprecate-link-to-positional-arguments.md @@ -0,0 +1,178 @@ +--- +Stage: Accepted +Start Date: 2021-01-05 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: https://github.com/emberjs/rfcs/pull/698 +--- + + + +# Deprecate Component Positional Arguments + +## Summary + +We propose to deprecate invoking the `` component with positional +arguments, in favor of the equivalent named arguments introduced in +[RFC #459](0459-angle-bracket-built-in-components.md). We also propose to +deprecate the `(query-params)` helper, which is only needed when invoking the +`` component with positional arguments. + +## Motivation + +In modern Ember, the idomatic way to invoke most componnts is to use the +[angle bracket syntax](0311-angle-bracket-invocation.md) along with the named +arguments `@` syntax. On the other hand, curly invocations are now reserved for +"helper-like" and "control-flow" components. + +The `` built-in component started life as a "helper" in the early days +of Ember, even before an official components API was created. Over time, it +became clear that `` is better classified as a component than a helper +in modern Ember, and the learning materials have been updated accordingly. + +This historical origin meant that `` was designed to accept positional +arguments exclusively, as was common with most helpers at the time. The angle +bracket syntax, on the other hand, accepts named arguments exclusively. + +Another downside to the positional arguments syntax was it required the use of +the `(query-params)` helper to distinguish query params from model arguments. + +Finally, the meaning of the positional arugments also changes slightly when the +component is invoked with or without a block, which made things needlessly +confusing. + +To address these issues, [RFC #459](0459-angle-bracket-built-in-components.md) +introduced explicit equivalent names for the positional arguments that were +accepted by the `` component. This allowed it to be invoked with the +same angle bracket syntax and avoided the other confusions mentioned above. + +These features were made available since v3.10 and are the idomatic thing to do +in modern Ember codebase. + +Given that the feature are now available on all currently-supported Ember +versions and the community had adequate time to make the transition, this would +be a good time to deprecate the obselete features to reduce confusion as well +as implementation complexity. + +In particular, some of the obselete features required capabilities not usually +available to other components, such as knowing whether a block was passed or +not and relies on "AST transforms" to normalize some of the differences. These +implementation strategies introduces unnecessary complexity in the internals +that sometimes causes bugs or other surprising behaviors. + +## Transition Path + +```hbs +Deprecated: + +{{link-to "About Us" "about"}} + ~~~~~~~~~~~~~~~~~~ + +Invoking the `` component with positional arguments is deprecated. +Instead, please use the equivalent named arguments (`@route`) and pass a +block for the link's content. + +About Us +``` + +```hbs +Deprecated: + +{{#link-to "about"}}About Us{{/link-to}} + ~~~~~~~ + +Invoking the `` component with positional arguments is deprecated. +Instead, please use the equivalent named arguments (`@route`). + +Replacement: + +About Us +``` + + +```hbs +Deprecated: + +{{#link-to "post" @post}}Read {{@post.title}}...{{/link-to}} + ~~~~~~~~~~~~ + +Invoking the `` component with positional arguments is deprecated. +Instead, please use the equivalent named arguments (`@route`, `@model`). + +Replacement: + +Read {{@post.title}}... +``` + +```hbs +Deprecated: + +{{#link-to "post.comment" @comment.post @comment}} + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Comment by {{@comment.author.name}} on {{@comment.date}} +{{/link-to}} + +Invoking the `` component with positional arguments is deprecated. +Instead, please use the equivalent named arguments (`@route`, `@models`). + +Replacement: + + + Comment by {{comment.author.name}} on {{comment.date}} + +``` + +```hbs +Deprecated: + +{{#link-to "posts" (query-params direction="desc" showArchived=false)}} + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Recent Posts +{{/link-to}} + +Invoking the `` component with positional arguments is deprecated. +Instead, please use the equivalent named arguments (`@route`, `@query`) and the +`hash` helper. + +Replacement: + + + Recent Posts + +``` + +These migrations can be automated using the [angle brackets codemod](https://github.com/ember-codemods/ember-angle-brackets-codemod). + +## How We Teach This + +The Octane learning materials have already been updated to use the latest +idioms, so no changes are necessary. The API documentation should be updated +to mark the obselete features and the `(query-params)` helper as deprecated. + +A deprecation guide will need to be written using the same examples from the +[Transition Path](#transition-path) section. The guide should also promote the +use of the codemod to automate the migration. + +## Drawbacks + +None. + +## Alternatives + +None. + +## Unresolved questions + +None. From e7c2062ec9e3201446861c057d5e16b03ae33b58 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Sat, 9 Jan 2021 15:24:22 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Matthew Beale --- text/0698-deprecate-link-to-positional-arguments.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0698-deprecate-link-to-positional-arguments.md b/text/0698-deprecate-link-to-positional-arguments.md index e1b6ae7202..a2271b3ced 100644 --- a/text/0698-deprecate-link-to-positional-arguments.md +++ b/text/0698-deprecate-link-to-positional-arguments.md @@ -32,7 +32,7 @@ deprecate the `(query-params)` helper, which is only needed when invoking the ## Motivation -In modern Ember, the idomatic way to invoke most componnts is to use the +In modern Ember, the idiomatic way to invoke most components is to use the [angle bracket syntax](0311-angle-bracket-invocation.md) along with the named arguments `@` syntax. On the other hand, curly invocations are now reserved for "helper-like" and "control-flow" components. @@ -63,10 +63,10 @@ in modern Ember codebase. Given that the feature are now available on all currently-supported Ember versions and the community had adequate time to make the transition, this would -be a good time to deprecate the obselete features to reduce confusion as well +be a good time to deprecate the obsolete features to reduce confusion as well as implementation complexity. -In particular, some of the obselete features required capabilities not usually +In particular, some of the obsolete features required capabilities not usually available to other components, such as knowing whether a block was passed or not and relies on "AST transforms" to normalize some of the differences. These implementation strategies introduces unnecessary complexity in the internals @@ -159,7 +159,7 @@ These migrations can be automated using the [angle brackets codemod](https://git The Octane learning materials have already been updated to use the latest idioms, so no changes are necessary. The API documentation should be updated -to mark the obselete features and the `(query-params)` helper as deprecated. +to mark the obsolete features and the `(query-params)` helper as deprecated. A deprecation guide will need to be written using the same examples from the [Transition Path](#transition-path) section. The guide should also promote the