Add for and since options to depreacte() function

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.
mehulkar · Oct 7, 2020 · 1f420ce · 1f420ce
1 parent ec74ab4
commit 1f420ce
Show file tree

Hide file tree

Showing 20 changed files with 313 additions and 11 deletions.
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,
 };