Merge pull request #690 from emberjs/deprecate-attrs-in-templates

text/0690-deprecate-attrs-in-templates.md

@@ -0,0 +1,71 @@
+---
+Stage: Accepted
+Start Date: 2020-12-22
+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/690
+---
+
+# Deprecate using `{{attrs}}` in templates
+
+## Summary
+
+The `{{attrs}}` object in templates is an alternative way for users to reference
+named arguments directly in a template.
+
+```hbs
+{{attrs.foo}}
+
+{{! is equivalent to }}
+{{@foo}}
+```
+
+It was a legacy API that existed prior to named arguments being introduced in
+Ember, and has continued to be supported via a template transform for some time.
+This RFC proposes that we deprecate this functionality in favor of directly
+using named arguments.
+
+## Motivation
+
+The `{{attrs}}` syntax was from a previous iteration of the concepts that
+eventually became named argument syntax. Now that named arguments exist in the
+framework, and are considered the best practice, there is no reason to continue
+supporting this syntax.
+
+## Transition Path
+
+Users who currently rely on referencing `{{attrs}}` can convert their references
+to named arguments. This should be highly codemoddable, and we will attempt to
+make a codemod to help out with the transition.
+
+## How We Teach This
+
+### Deprecation Guide
+
+The `{{attrs}}` object was an alternative way to reference named arguments in
+templates that was introduced prior to named arguments syntax being finalized.
+References to properties on `{{attrs}}` can be converted directly to named
+argument syntax.
+
+Before:
+
+```hbs
+{{attrs.foo}}
+{{this.attrs.foo.bar}}
+{{deeply (nested attrs.foobar.baz)}}
+```
+
+After:
+
+```hbs
+ {{@foo}}
+ {{@foo.bar}}
+ {{deeply (nested @foobar.baz)}}
+ ```
+
+## Drawbacks
+
+- None