docs: deprecation workflow (#1067)

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

1 files changed, 25 insertions, 6 deletions

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}.`);