docs: deprecation workflow (#1067)

Co-authored-by: Eric Cheng <[email protected]>

6 files changed, 70 insertions, 24 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b840ac80..0618a388 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -49,6 +49,28 @@ You can view a generated code coverage report at `coverage/index.html`.
 
 After adding new or updating existing locale data, you need to run `pnpm run generate:locales` to generate/update the related files.
 
+## Deprecation workflow
+
+If you ever find yourself deprecating something in the source code, you can follow these steps to save yourself (and the reviewers) some trouble.
+
+If the code you want to deprecate is a property, convert it to a [getter](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) first. Now that you have a function, the first thing you want to do is call the internal [`deprecated` function](src/internal/deprecated.ts). Afterwards, add a `@deprecated` parameter to the end of the JSDoc with a human readable description message with a suitable replacement for the deprecated function. Lastly, add a `@see` parameter to the JSDoc with a link to the replacement in the faker library (if it exists). The syntax for the link is `faker.[module].[function]`.
+
+Example:
+
+```ts
+/**
+ * @see faker.cat.random
+ *
+ * @deprecated Use faker.cat.random() instead.
+ */
+get cat() {
+  deprecated({
+    deprecated: 'faker.animal.cat',
+  });
+  return 'cat';
+}
+```
+
 ## Developing the docs
 
 Before running the docs, build the Faker dist, it's used inside of certain routes.
diff --git a/src/internal/deprecated.ts b/src/internal/deprecated.ts
index ab67b60a..f0668bc5 100644
--- a/src/internal/deprecated.ts
+++ b/src/internal/deprecated.ts
@@ -1,28 +1,47 @@
 /* eslint-disable jsdoc/check-tag-names */
 /* eslint-disable jsdoc/require-param */
 
+/**
+ * A deprecation should never be done in a patch.
+ */
+type DeprecationSemVer = `${number}.${number}`;
+
 /** @internal */
 export interface DeprecatedOptions {
+  /**
+   * The name of the function, following the syntax `faker.[module].[function]()`.
+   */
   deprecated: string;
+  /**
+   * An alternative solution.
+   */
   proposed?: string;
-  since?: string;
-  until?: string;
+  /**
+   * The semver since when this is deprecated.
+   */
+  since?: DeprecationSemVer;
+  /**
+   * The semver when this will be removed.
+   */
+  until?: DeprecationSemVer;
 }
 
-/** @internal */
+/**
+ * @internal
+ */
 export function deprecated(opts: DeprecatedOptions): void {
   let message = `[@faker-js/faker]: ${opts.deprecated} is deprecated`;
 
   if (opts.since) {
-    message += ` since ${opts.since}`;
+    message += ` since v${opts.since}`;
   }
 
   if (opts.until) {
-    message += ` and will be removed in ${opts.until}`;
+    message += ` and will be removed in v${opts.until}`;
   }
 
   if (opts.proposed) {
-    message += `. Please use ${opts.proposed} instead`;
+    message += `. Please use ${opts.proposed} instead.`;
   }
 
   console.warn(`${message}.`);
diff --git a/src/modules/address/index.ts b/src/modules/address/index.ts
index e3c568fd..7c55bb51 100644
--- a/src/modules/address/index.ts
+++ b/src/modules/address/index.ts
@@ -76,8 +76,8 @@ export class Address {
       deprecated({
         deprecated: 'faker.address.city(format)',
         proposed: 'faker.address.city() or faker.fake(format)',
-        since: 'v7.0',
-        until: 'v8.0',
+        since: '7.0',
+        until: '8.0',
       });
     }
     const formats = this.faker.definitions.address.city;
@@ -98,13 +98,14 @@ export class Address {
    * faker.address.cityPrefix() // 'East'
    *
    * @deprecated
+   * Use `faker.address.city()` instead.
    */
   cityPrefix(): string {
     deprecated({
       deprecated: 'faker.address.cityPrefix()',
       proposed: "faker.address.city() or faker.fake('{{address.city_prefix}}')",
-      since: 'v7.2',
-      until: 'v8.0',
+      since: '7.2',
+      until: '8.0',
     });
     return this.faker.helpers.arrayElement(
       this.faker.definitions.address.city_prefix
@@ -120,13 +121,14 @@ export class Address {
    * faker.address.citySuffix() // 'mouth'
    *
    * @deprecated
+   * Use `faker.address.city()` instead.
    */
   citySuffix(): string {
     deprecated({
       deprecated: 'faker.address.citySuffix()',
       proposed: "faker.address.city() or faker.fake('{{address.city_suffix}}')",
-      since: 'v7.2',
-      until: 'v8.0',
+      since: '7.2',
+      until: '8.0',
     });
     return this.faker.helpers.arrayElement(
       this.faker.definitions.address.city_suffix
@@ -185,8 +187,8 @@ export class Address {
           'faker.address.streetName() without address.street_name definitions',
         proposed:
           'faker.address.street() or provide address.street_name definitions',
-        since: 'v7.0',
-        until: 'v8.0',
+        since: '7.0',
+        until: '8.0',
       });
       return this.street();
     }
diff --git a/src/modules/commerce/index.ts b/src/modules/commerce/index.ts
index d17c473b..2dcb4ca3 100644
--- a/src/modules/commerce/index.ts
+++ b/src/modules/commerce/index.ts
@@ -22,13 +22,14 @@ export class Commerce {
    * faker.commerce.color() // 'red'
    *
    * @deprecated
+   * Use `faker.color.human()` instead.
    */
   color(): string {
     deprecated({
       deprecated: 'faker.commerce.color()',
       proposed: 'faker.color.human()',
-      since: 'v7.0.0',
-      until: 'v8.0.0',
+      since: '7.0',
+      until: '8.0',
     });
     return this.faker.color.human();
   }
diff --git a/src/modules/phone/index.ts b/src/modules/phone/index.ts
index 68f97bf6..08da0821 100644
--- a/src/modules/phone/index.ts
+++ b/src/modules/phone/index.ts
@@ -33,8 +33,8 @@ export class Phone {
     deprecated({
       deprecated: 'faker.phone.phoneNumber()',
       proposed: 'faker.phone.number()',
-      since: 'v7.3',
-      until: 'v8.0',
+      since: '7.3',
+      until: '8.0',
     });
     return this.faker.phone.number(format);
   }
@@ -71,14 +71,15 @@ export class Phone {
    * faker.phone.phoneNumberFormat(3) // '282.652.3201'
    *
    * @deprecated
+   * Use faker.phone.phoneNumber() instead.
    */
   phoneNumberFormat(phoneFormatsArrayIndex = 0): string {
     deprecated({
       deprecated: 'faker.phone.phoneNumberFormat()',
       proposed:
         'faker.phone.phoneNumber() or faker.helpers.replaceSymbolWithNumber(format)',
-      since: 'v7.0',
-      until: 'v8.0',
+      since: '7.0',
+      until: '8.0',
     });
     return this.faker.helpers.replaceSymbolWithNumber(
       this.faker.definitions.phone_number.formats[phoneFormatsArrayIndex]
@@ -95,13 +96,14 @@ export class Phone {
    * faker.phone.phoneFormats() // '!##.!##.####'
    *
    * @deprecated
+   * Use `faker.phone.phoneNumber()` instead.
    */
   phoneFormats(): string {
     deprecated({
       deprecated: 'faker.phone.phoneFormats()',
       proposed: 'faker.phone.phoneNumber()',
-      since: 'v7.0',
-      until: 'v8.0',
+      since: '7.0',
+      until: '8.0',
     });
     return this.faker.helpers.arrayElement(
       this.faker.definitions.phone_number.formats
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index 616dc4dd..727ec8fb 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -273,8 +273,8 @@ export class Random {
       deprecated({
         deprecated: 'faker.random.alpha({ upcase: true })',
         proposed: "faker.random.alpha({ casing: 'upper' })",
-        since: 'v7.0',
-        until: 'v8.0',
+        since: '7.0',
+        until: '8.0',
       });
     }