From 4bbb95af0f9fe08f3f9db1cc4e91245973e4bd0c Mon Sep 17 00:00:00 2001
From: Keshav Biswa <keshavbiswa21@gmail.com>
Date: Tue, 19 Mar 2024 21:10:36 +0530
Subject: [PATCH 1/2] Added docs for deprecator in CONTRIBUTING.md

---
 CONTRIBUTING.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4eb0712a95..18861a2445 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -158,6 +158,33 @@ module Faker
 end
 ```
 
+## Deprecating Generators
+
+To deprecate entire generators, we use the [Faker::Deprecator](https://github.com/faker-ruby/faker/blob/main/lib/helpers/deprecator.rb) helper module. Here's how to use it:
+
+- include the `Faker::Deprecator` module after the class definition.
+- add the `deprecate_generator` method with the old and new class names as arguments.
+
+```rb 
+module Faker
+  class IdNumber < Base
+    ## methods
+  end
+
+  include Faker::Deprecator
+  deprecate_generator('IDNumber', IdNumber)
+end
+```
+
+`Faker::IDNumber` is now deprecated. Despite the deprecation, it will still be available with logged warnings and will be removed in the next major release.
+
+```rb
+Faker::IDNumber.valid #=> "552-56-3593"
+
+## Deprecation warning
+DEPRECATION WARNING: Faker::IDNumber is deprecated. Use Faker::IdNumber instead.
+```
+
 ## YAML files
 
 Please use dash syntax for YAML arrays. The dash syntax facilitates code reviews by making it easier to see what items were added or removed from the lists.

From b6d37eacd73d83188d35dba013d4c44223f71440 Mon Sep 17 00:00:00 2001
From: Keshav Biswa <keshavbiswa21@gmail.com>
Date: Tue, 26 Mar 2024 10:50:23 +0530
Subject: [PATCH 2/2] Updated CONTRIBUTING.md with test instructions for
 deprecated Generators

---
 CONTRIBUTING.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 18861a2445..0610d23071 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -160,7 +160,8 @@ end
 
 ## Deprecating Generators
 
-To deprecate entire generators, we use the [Faker::Deprecator](https://github.com/faker-ruby/faker/blob/main/lib/helpers/deprecator.rb) helper module. Here's how to use it:
+To deprecate entire generators and provide backwards compatibility when it's possible, use this custom [Faker::Deprecator](https://github.com/faker-ruby/faker/blob/main/lib/helpers/deprecator.rb) helper module. 
+It's useful for renaming a generator, for example, renaming `IDNumber` to `IdNumber`. Here's how to use it:
 
 - include the `Faker::Deprecator` module after the class definition.
 - add the `deprecate_generator` method with the old and new class names as arguments.
@@ -185,6 +186,10 @@ Faker::IDNumber.valid #=> "552-56-3593"
 DEPRECATION WARNING: Faker::IDNumber is deprecated. Use Faker::IdNumber instead.
 ```
 
+We recommend adding tests for both the deprecated and new generators to ensure that the deprecation process is working as expected.
+Check out this [PR](https://github.com/faker-ruby/faker/pull/2856) for reference.
+
+
 ## YAML files
 
 Please use dash syntax for YAML arrays. The dash syntax facilitates code reviews by making it easier to see what items were added or removed from the lists.