Add for and since options to depreacte() function

Mehul Kar · Mehul Kar · commit 1f420ce88572 · 2020-10-07T15:51:13.000-05:00
This implements the first stage of the Deprecation Staging RFC emberjs/rfcs#649 This commit also: - deprecates the usage of deprecate() function without passing these options - Updates all the usages of deprecate() in the repo to pass these options.
diff --git a/packages/@ember/-internals/glimmer/lib/component.ts b/packages/@ember/-internals/glimmer/lib/component.ts
@@ -752,6 +752,10 @@ const Component = CoreView.extend(
           id: 'ember-views.event-dispatcher.mouseenter-leave-move',
           until: '4.0.0',
           url: 'https://emberjs.com/deprecations/v3.x#toc_component-mouseenter-leave-move',
+          for: 'ember-source',
+          since: {
+            enabled: '3.13.0-beta.1',
+          },
         }
       );
       deprecate(
@@ -761,6 +765,10 @@ const Component = CoreView.extend(
           id: 'ember-views.event-dispatcher.mouseenter-leave-move',
           until: '4.0.0',
           url: 'https://emberjs.com/deprecations/v3.x#toc_component-mouseenter-leave-move',
+          for: 'ember-source',
+          since: {
+            enabled: '3.13.0-beta.1',
+          },
         }
       );
       deprecate(
@@ -770,6 +778,10 @@ const Component = CoreView.extend(
           id: 'ember-views.event-dispatcher.mouseenter-leave-move',
           until: '4.0.0',
           url: 'https://emberjs.com/deprecations/v3.x#toc_component-mouseenter-leave-move',
+          for: 'ember-source',
+          since: {
+            enabled: '3.13.0-beta.1',
+          },
         }
       );
     },
diff --git a/packages/@ember/-internals/glimmer/lib/environment.ts b/packages/@ember/-internals/glimmer/lib/environment.ts
@@ -64,6 +64,10 @@ if (DEBUG) {
       deprecate(message, false, {
         id: 'autotracking.mutation-after-consumption',
         until: '4.0.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.21.0',
+        },
       });
     },
 
diff --git a/packages/@ember/-internals/glimmer/lib/helpers/action.ts b/packages/@ember/-internals/glimmer/lib/helpers/action.ts
@@ -415,6 +415,10 @@ function makeClosureAction(
       {
         until: '3.25.0',
         id: 'actions.custom-invoke-invokable',
+        for: 'ember-source',
+        since: {
+          enabled: '3.23.0-beta.1',
+        },
       }
     );
 
diff --git a/packages/@ember/-internals/glimmer/lib/modifiers/action.ts b/packages/@ember/-internals/glimmer/lib/modifiers/action.ts
@@ -156,6 +156,10 @@ export class ActionState {
           {
             until: '3.25.0',
             id: 'actions.custom-invoke-invokable',
+            for: 'ember-source',
+            since: {
+              enabled: '3.23.0-beta.1',
+            },
           }
         );
 
@@ -226,6 +230,10 @@ export default class ActionModifierManager implements ModifierManager<ActionStat
         id: 'ember-views.event-dispatcher.mouseenter-leave-move',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x#toc_action-mouseenter-leave-move',
+        for: 'ember-source',
+        since: {
+          enabled: '3.13.0-beta.1',
+        },
       }
     );
 
diff --git a/packages/@ember/-internals/glimmer/lib/resolver.ts b/packages/@ember/-internals/glimmer/lib/resolver.ts
@@ -149,6 +149,10 @@ if (PARTIALS) {
         id: 'ember-views.partial',
         until: '4.0.0',
         url: 'https://deprecations.emberjs.com/v3.x#toc_ember-views-partial',
+        for: 'ember-source',
+        since: {
+          enabled: '3.15.0-beta.1',
+        },
       }
     );
 
diff --git a/packages/@ember/-internals/glimmer/lib/utils/bindings.ts b/packages/@ember/-internals/glimmer/lib/utils/bindings.ts
@@ -112,6 +112,10 @@ if (EMBER_COMPONENT_IS_VISIBLE) {
             id: 'ember-component.is-visible',
             until: '4.0.0',
             url: 'https://deprecations.emberjs.com/v3.x#toc_ember-component-is-visible',
+            for: 'ember-source',
+            since: {
+              enabled: '3.15.0-beta.1',
+            },
           }
         );
       }
diff --git a/packages/@ember/-internals/glimmer/lib/utils/managers.ts b/packages/@ember/-internals/glimmer/lib/utils/managers.ts
@@ -171,6 +171,10 @@ export function setComponentManager(
         id: 'deprecate-string-based-component-manager',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x/#toc_component-manager-string-lookup',
+        for: 'ember-source',
+        since: {
+          enabled: '3.8.0',
+        },
       }
     );
     factory = function (owner: Owner) {
diff --git a/packages/@ember/-internals/meta/lib/meta.ts b/packages/@ember/-internals/meta/lib/meta.ts
@@ -144,6 +144,10 @@ export class Meta {
       {
         id: 'meta-destruction-apis',
         until: '3.25.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.21.0',
+        },
       }
     );
   }
@@ -155,6 +159,10 @@ export class Meta {
       {
         id: 'meta-destruction-apis',
         until: '3.25.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.21.0',
+        },
       }
     );
   }
@@ -166,6 +174,10 @@ export class Meta {
       {
         id: 'meta-destruction-apis',
         until: '3.25.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.21.0',
+        },
       }
     );
 
@@ -179,6 +191,10 @@ export class Meta {
       {
         id: 'meta-destruction-apis',
         until: '3.25.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.21.0',
+        },
       }
     );
 
diff --git a/packages/@ember/-internals/metal/lib/chain-tags.ts b/packages/@ember/-internals/metal/lib/chain-tags.ts
@@ -109,6 +109,10 @@ function getChainTags(
         {
           until: '3.17.0',
           id: 'ember-metal.computed-deep-each',
+          for: 'ember-source',
+          since: {
+            enabled: '3.13.0-beta.3',
+          },
         }
       );
 
diff --git a/packages/@ember/-internals/metal/lib/computed.ts b/packages/@ember/-internals/metal/lib/computed.ts
@@ -507,6 +507,10 @@ export class ComputedProperty extends ComputedDescriptor {
         id: 'computed-property.override',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x#toc_computed-property-override',
+        for: 'ember-source',
+        since: {
+          enabled: '3.9.0-beta.1',
+        },
       }
     );
 
@@ -715,6 +719,10 @@ class ComputedDecoratorImpl extends Function {
         id: 'computed-property.volatile',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x#toc_computed-property-volatile',
+        for: 'ember-source',
+        since: {
+          enabled: '3.9.0-beta.1',
+        },
       }
     );
     (descriptorForDecorator(this) as ComputedProperty)._volatile = true;
@@ -786,6 +794,10 @@ class ComputedDecoratorImpl extends Function {
         id: 'computed-property.property',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x#toc_computed-property-property',
+        for: 'ember-source',
+        since: {
+          enabled: '3.9.0-beta.1',
+        },
       }
     );
     (descriptorForDecorator(this) as ComputedProperty)._property(...keys);
diff --git a/packages/@ember/-internals/metal/lib/mixin.ts b/packages/@ember/-internals/metal/lib/mixin.ts
@@ -826,6 +826,10 @@ if (ALIAS_METHOD) {
         id: 'object.alias-method',
         until: '4.0.0',
         url: 'https://emberjs.com/deprecations/v3.x#toc_object-alias-method',
+        for: 'ember-source',
+        since: {
+          enabled: '3.9.0',
+        },
       }
     );
     return new AliasImpl(methodName);
diff --git a/packages/@ember/-internals/metal/lib/property_get.ts b/packages/@ember/-internals/metal/lib/property_get.ts
@@ -189,6 +189,10 @@ export function getWithDefault<T extends object, K extends Extract<keyof T, stri
       id: 'ember-metal.get-with-default',
       until: '4.0.0',
       url: 'https://deprecations.emberjs.com/v3.x#toc_ember-metal-get-with-default',
+      for: 'ember-source',
+      since: {
+        enabled: '3.21.0',
+      },
     }
   );
 
diff --git a/packages/@ember/-internals/owner/index.ts b/packages/@ember/-internals/owner/index.ts
@@ -99,6 +99,10 @@ export function getOwner(object: any): Owner {
       {
         id: 'owner.legacy-owner-injection',
         until: '3.25.0',
+        for: 'ember-source',
+        since: {
+          enabled: '3.22.0',
+        },
       }
     );
   }
diff --git a/packages/@ember/-internals/routing/lib/system/route.ts b/packages/@ember/-internals/routing/lib/system/route.ts
@@ -2640,6 +2640,10 @@ if (ROUTER_EVENTS) {
             id: 'deprecate-router-events',
             until: '4.0.0',
             url: 'https://emberjs.com/deprecations/v3.x#toc_deprecate-router-events',
+            for: 'ember-source',
+            since: {
+              enabled: '3.11.0',
+            },
           }
         );
       }
@@ -2652,6 +2656,10 @@ if (ROUTER_EVENTS) {
             id: 'deprecate-router-events',
             until: '4.0.0',
             url: 'https://emberjs.com/deprecations/v3.x#toc_deprecate-router-events',
+            for: 'ember-source',
+            since: {
+              enabled: '3.11.0',
+            },
           }
         );
       }
diff --git a/packages/@ember/-internals/routing/lib/system/router.ts b/packages/@ember/-internals/routing/lib/system/router.ts
@@ -230,6 +230,10 @@ class EmberRouter extends EmberObject {
                 id: 'deprecate-router-events',
                 until: '4.0.0',
                 url: 'https://emberjs.com/deprecations/v3.x#toc_deprecate-router-events',
+                for: 'ember-source',
+                since: {
+                  enabled: '3.11.0',
+                },
               }
             );
           }
@@ -251,6 +255,10 @@ class EmberRouter extends EmberObject {
                 id: 'deprecate-router-events',
                 until: '4.0.0',
                 url: 'https://emberjs.com/deprecations/v3.x#toc_deprecate-router-events',
+                for: 'ember-source',
+                since: {
+                  enabled: '3.11.0',
+                },
               }
             );
           }
@@ -1486,6 +1494,10 @@ function updatePaths(router: EmberRouter) {
               until: '4.0.0',
               url:
                 'https://emberjs.com/deprecations/v3.x#toc_application-controller-router-properties',
+              for: 'ember-source',
+              since: {
+                enabled: '3.10.0-beta.1',
+              },
             }
           );
           return get(router, 'currentPath');
@@ -1505,6 +1517,10 @@ function updatePaths(router: EmberRouter) {
               until: '4.0.0',
               url:
                 'https://emberjs.com/deprecations/v3.x#toc_application-controller-router-properties',
+              for: 'ember-source',
+              since: {
+                enabled: '3.10.0-beta.1',
+              },
             }
           );
           return get(router, 'currentRouteName');
diff --git a/packages/@ember/debug/lib/deprecate.ts b/packages/@ember/debug/lib/deprecate.ts
@@ -10,13 +10,18 @@ declare global {
   };
 }
 
+export type DeprecationStages = 'available' | 'enabled';
+
 export interface DeprecationOptions {
   id: string;
   until: string;
   url?: string;
+  for: string;
+  since: Partial<Record<DeprecationStages, string>>;
 }
 
 export type DeprecateFunc = (message: string, test?: boolean, options?: DeprecationOptions) => void;
+export type MissingOptionDeprecateFunc = (id: string) => string;
 
 /**
  @module @ember/debug
@@ -64,7 +69,11 @@ let registerHandler: (handler: HandlerCallback) => void = () => {};
 let missingOptionsDeprecation: string;
 let missingOptionsIdDeprecation: string;
 let missingOptionsUntilDeprecation: string;
+let missingOptionsForDeprecation: MissingOptionDeprecateFunc = () => '';
+let missingOptionsSinceDeprecation: MissingOptionDeprecateFunc = () => '';
 let deprecate: DeprecateFunc = () => {};
+let FOR_MISSING_DEPRECATIONS = new Set();
+let SINCE_MISSING_DEPRECATIONS = new Set();
 
 if (DEBUG) {
   registerHandler = function registerHandler(handler: HandlerCallback) {
@@ -154,6 +163,13 @@ if (DEBUG) {
     '`options` should include `id` and `until` properties.';
   missingOptionsIdDeprecation = 'When calling `deprecate` you must provide `id` in options.';
   missingOptionsUntilDeprecation = 'When calling `deprecate` you must provide `until` in options.';
+
+  missingOptionsForDeprecation = (id: string) => {
+    return `When calling \`deprecate\` you must provide \`for\` in options. Missing options.for in "${id}" deprecation`;
+  };
+  missingOptionsSinceDeprecation = (id: string) => {
+    return `When calling \`deprecate\` you must provide \`since\` in options. Missing options.since in "${id}" deprecation`;
+  };
   /**
    @module @ember/debug
    @public
@@ -176,8 +192,10 @@ if (DEBUG) {
       "view.helper.select".
     @param {string} options.until The version of Ember when this deprecation
       warning will be removed.
+    @param {String} options.for A namespace for the deprecation, usually the package name
+    @param {Object} options.since Describes when the deprecation became available and enabled.
     @param {String} [options.url] An optional url to the transition guide on the
-      emberjs.com website.
+          emberjs.com website.
     @static
     @public
     @since 1.0.0
@@ -187,6 +205,32 @@ if (DEBUG) {
     assert(missingOptionsIdDeprecation, Boolean(options!.id));
     assert(missingOptionsUntilDeprecation, Boolean(options!.until));
 
+    if (!options!.for && !FOR_MISSING_DEPRECATIONS.has(options!.id)) {
+      FOR_MISSING_DEPRECATIONS.add(options!.id);
+
+      deprecate(missingOptionsForDeprecation(options!.id), Boolean(options!.for), {
+        id: 'ember-source.deprecation-without-for',
+        until: '4.0.0',
+        for: 'ember-source',
+        since: {
+          available: '3.24.0',
+        },
+      });
+    }
+
+    if (!options!.since && !SINCE_MISSING_DEPRECATIONS.has(options!.id)) {
+      SINCE_MISSING_DEPRECATIONS.add(options!.id);
+
+      deprecate(missingOptionsSinceDeprecation(options!.id), Boolean(options!.since), {
+        id: 'ember-source.deprecation-without-since',
+        until: '4.0.0',
+        for: 'ember-source',
+        since: {
+          available: '3.24.0',
+        },
+      });
+    }
+
     invoke('deprecate', message, test, options);
   };
 }
@@ -198,4 +242,8 @@ export {
   missingOptionsDeprecation,
   missingOptionsIdDeprecation,
   missingOptionsUntilDeprecation,
+  missingOptionsForDeprecation,
+  missingOptionsSinceDeprecation,
+  FOR_MISSING_DEPRECATIONS,
+  SINCE_MISSING_DEPRECATIONS,
 };
diff --git a/packages/@ember/debug/tests/main_test.js b/packages/@ember/debug/tests/main_test.js
diff --git a/packages/@ember/polyfills/lib/merge.ts b/packages/@ember/polyfills/lib/merge.ts
diff --git a/packages/ember-template-compiler/lib/plugins/deprecate-send-action.ts b/packages/ember-template-compiler/lib/plugins/deprecate-send-action.ts
diff --git a/packages/ember-template-compiler/lib/plugins/transform-in-element.ts b/packages/ember-template-compiler/lib/plugins/transform-in-element.ts

Original file line number	Diff line number	Diff line change
`@@ -415,6 +415,10 @@ function makeClosureAction(`
`415`	`415`	`{`
`416`	`416`	`until: '3.25.0',`
`417`	`417`	`id: 'actions.custom-invoke-invokable',`
	`418`	`+ for: 'ember-source',`
	`419`	`+ since: {`
	`420`	`+ enabled: '3.23.0-beta.1',`
	`421`	`+ },`
`418`	`422`	`}`
`419`	`423`	`);`
`420`	`424`
Original file line number	Diff line number	Diff line change
`@@ -156,6 +156,10 @@ export class ActionState {`
`156`	`156`	`{`
`157`	`157`	`until: '3.25.0',`
`158`	`158`	`id: 'actions.custom-invoke-invokable',`
	`159`	`+ for: 'ember-source',`
	`160`	`+ since: {`
	`161`	`+ enabled: '3.23.0-beta.1',`
	`162`	`+ },`
`159`	`163`	`}`
`160`	`164`	`);`
`161`	`165`
`@@ -226,6 +230,10 @@ export default class ActionModifierManager implements ModifierManager<ActionStat`
`226`	`230`	`id: 'ember-views.event-dispatcher.mouseenter-leave-move',`
`227`	`231`	`until: '4.0.0',`
`228`	`232`	`url: 'https://emberjs.com/deprecations/v3.x#toc_action-mouseenter-leave-move',`
	`233`	`+ for: 'ember-source',`
	`234`	`+ since: {`
	`235`	`+ enabled: '3.13.0-beta.1',`
	`236`	`+ },`
`229`	`237`	`}`
`230`	`238`	`);`
`231`	`239`
Original file line number	Diff line number	Diff line change
`@@ -112,6 +112,10 @@ if (EMBER_COMPONENT_IS_VISIBLE) {`
`112`	`112`	`id: 'ember-component.is-visible',`
`113`	`113`	`until: '4.0.0',`
`114`	`114`	`url: 'https://deprecations.emberjs.com/v3.x#toc_ember-component-is-visible',`
	`115`	`+ for: 'ember-source',`
	`116`	`+ since: {`
	`117`	`+ enabled: '3.15.0-beta.1',`
	`118`	`+ },`
`115`	`119`	`}`
`116`	`120`	`);`
`117`	`121`	`}`
Original file line number	Diff line number	Diff line change
`@@ -144,6 +144,10 @@ export class Meta {`
`144`	`144`	`{`
`145`	`145`	`id: 'meta-destruction-apis',`
`146`	`146`	`until: '3.25.0',`
	`147`	`+ for: 'ember-source',`
	`148`	`+ since: {`
	`149`	`+ enabled: '3.21.0',`
	`150`	`+ },`
`147`	`151`	`}`
`148`	`152`	`);`
`149`	`153`	`}`
`@@ -155,6 +159,10 @@ export class Meta {`
`155`	`159`	`{`
`156`	`160`	`id: 'meta-destruction-apis',`
`157`	`161`	`until: '3.25.0',`
	`162`	`+ for: 'ember-source',`
	`163`	`+ since: {`
	`164`	`+ enabled: '3.21.0',`
	`165`	`+ },`
`158`	`166`	`}`
`159`	`167`	`);`
`160`	`168`	`}`
`@@ -166,6 +174,10 @@ export class Meta {`
`166`	`174`	`{`
`167`	`175`	`id: 'meta-destruction-apis',`
`168`	`176`	`until: '3.25.0',`
	`177`	`+ for: 'ember-source',`
	`178`	`+ since: {`
	`179`	`+ enabled: '3.21.0',`
	`180`	`+ },`
`169`	`181`	`}`
`170`	`182`	`);`
`171`	`183`
`@@ -179,6 +191,10 @@ export class Meta {`
`179`	`191`	`{`
`180`	`192`	`id: 'meta-destruction-apis',`
`181`	`193`	`until: '3.25.0',`
	`194`	`+ for: 'ember-source',`
	`195`	`+ since: {`
	`196`	`+ enabled: '3.21.0',`
	`197`	`+ },`
`182`	`198`	`}`
`183`	`199`	`);`
`184`	`200`
Original file line number	Diff line number	Diff line change
`@@ -109,6 +109,10 @@ function getChainTags(`
`109`	`109`	`{`
`110`	`110`	`until: '3.17.0',`
`111`	`111`	`id: 'ember-metal.computed-deep-each',`
	`112`	`+ for: 'ember-source',`
	`113`	`+ since: {`
	`114`	`+ enabled: '3.13.0-beta.3',`
	`115`	`+ },`
`112`	`116`	`}`
`113`	`117`	`);`
`114`	`118`