[RFC 698] Deprecate <LinkTo> positional arguments

packages/@ember/-internals/glimmer/lib/components/link-to.ts

@@ -6,7 +6,7 @@ import { alias, computed } from '@ember/-internals/metal';
 import { getOwner } from '@ember/-internals/owner';
 import RouterState from '@ember/-internals/routing/lib/system/router_state';
 import { isSimpleClick } from '@ember/-internals/views';
-import { assert, warn } from '@ember/debug';
+import { assert, deprecate, runInDebug, warn } from '@ember/debug';
 import { EngineInstance, getEngineParent } from '@ember/engine';
 import { flaggedInstrument } from '@ember/instrumentation';
 import { inject as injectService } from '@ember/service';
@@ -890,11 +890,13 @@ const LinkComponent = EmberComponent.extend({
       return;
     }
 
+    let hasBlock = this[HAS_BLOCK];
+
     params = params.slice();
 
     // Process the positional arguments, in order.
     // 1. Inline link title comes first, if present.
-    if (!this[HAS_BLOCK]) {
+    if (!hasBlock) {
       this.set('linkTitle', params.shift());
     }
 
@@ -917,6 +919,71 @@ const LinkComponent = EmberComponent.extend({
     // 4. Any remaining indices (if any) are `models`.
     this.set('model', UNDEFINED);
     this.set('models', params);
+
+    runInDebug(() => {
+      params = this.params.slice();
+
+      let equivalentNamedArgs = [];
+      let hasQueryParams = false;
+
+      // Process the positional arguments, in order.
+      // 1. Inline link title comes first, if present.
+      if (!hasBlock) {
+        params.shift();
+      }
+
+      // 2. The last argument is possibly the `query` object.
+      let query = params[params.length - 1];
+
+      if (query && query.isQueryParams) {
+        params.pop();
+        hasQueryParams = true;
+      }
+
+      // 3. If there is a `route`, it is now at index 0.
+      if (params.length > 0) {
+        params.shift();
+        equivalentNamedArgs.push('`@route`');
+      }
+
+      // 4. Any remaining params (if any) are `models`.
+      if (params.length === 1) {
+        equivalentNamedArgs.push('`@model`');
+      } else if (params.length > 1) {
+        equivalentNamedArgs.push('`@models`');
+      }
+
+      if (hasQueryParams) {
+        equivalentNamedArgs.push('`@query`');
+      }
+
+      if (equivalentNamedArgs.length > 0) {
+        let message = 'Invoking the `<LinkTo>` component with positional arguments is deprecated.';
+
+        message += `Please use the equivalent named arguments (${equivalentNamedArgs.join(', ')})`;
+
+        if (hasQueryParams) {
+          message += ' along with the `hash` helper';
+        }
+
+        if (!hasBlock) {
+          message += " and pass a block for the link's content.";
+        }
+
+        message += '.';
+
+        deprecate(message, false, {
+          id: 'ember-glimmer.link-to.positional-arguments',
+          until: '4.0.0',
+          for: 'ember-source',
+          url:
+            'https://deprecations.emberjs.com/v3.x#toc_ember-glimmer-link-to-positional-arguments',
+          since: {
+            enabled: '3.26.0-beta.1',
+          },
+        });
+      }
+    });
   },
 });
 

packages/@ember/-internals/glimmer/lib/helpers/query-param.ts

@@ -2,7 +2,7 @@
 @module ember
 */
 import { QueryParams } from '@ember/-internals/routing';
-import { assert } from '@ember/debug';
+import { assert, deprecate } from '@ember/debug';
 import { assign } from '@ember/polyfills';
 import { VMArguments } from '@glimmer/interfaces';
 import { createComputeRef } from '@glimmer/reference';
@@ -35,10 +35,24 @@ export default internalHelper((args: VMArguments) => {
 
   return createComputeRef(() => {
     assert(
-      "The `query-params` helper only accepts hash parameters, e.g. (query-params queryParamPropertyName='foo') as opposed to just (query-params 'foo')",
+      "The `query-params` helper only accepts named arguments, e.g. (query-params queryParamPropertyName='foo') as opposed to (query-params 'foo')",
       positional.length === 0
     );
 
+    deprecate(
+      'The `query-params` helper is deprecated. Invoke `<LinkTo>` with the `@query` named argument and the `hash` helper instead.',
+      false,
+      {
+        id: 'ember-glimmer.link-to.positional-arguments',
+        until: '4.0.0',
+        for: 'ember-source',
+        url: 'https://deprecations.emberjs.com/v3.x#toc_ember-glimmer-link-to-positional-arguments',
+        since: {
+          enabled: '3.26.0-beta.1',
+        },
+      }
+    );
+
     return new QueryParams(assign({}, reifyNamed(named) as any));
   });
 });

packages/@ember/-internals/glimmer/tests/integration/application/engine-test.js

@@ -889,7 +889,9 @@ moduleFor(
 
     ["@test query params don't have stickiness by default between model"](assert) {
       assert.expect(1);
-      let tmpl = '{{#link-to "category" 1337}}Category 1337{{/link-to}}';
+
+      let tmpl = '<LinkTo @route="category" @model={{1337}}>Category 1337</LinkTo>';
+
       this.setupAppAndRoutableEngine();
       this.additionalEngineRegistrations(function () {
         this.register('template:category', compile(tmpl));
@@ -928,7 +930,7 @@ moduleFor(
     ) {
       assert.expect(2);
       let tmpl =
-        '{{#link-to "author" 1337 class="author-1337"}}Author 1337{{/link-to}}{{#link-to "author" 1 class="author-1"}}Author 1{{/link-to}}';
+        '<LinkTo @route="author" @model={{1337}} class="author-1337">Author 1337</LinkTo><LinkTo @route="author" @model=1 class="author-1">Author 1</LinkTo>';
       this.setupAppAndRoutableEngine();
       this.additionalEngineRegistrations(function () {
         this.register('template:author', compile(tmpl));