Document deprecators for library authors

Author: etiennebarrie

activesupport/CHANGELOG.md

@@ -1,3 +1,39 @@
+*   Deprecate usage of the singleton `ActiveSupport::Deprecation`.
+
+    All usage of `ActiveSupport::Deprecation` as a singleton is deprecated, the most common one being
+    `ActiveSupport::Deprecation.warn`. Gem authors should now create their own deprecator (`ActiveSupport::Deprecation`
+    object), and use it to emit deprecation warnings.
+
+    Calling any of the following without specifying a deprecator argument is also deprecated:
+      * Module.deprecate
+      * deprecate_constant
+      * DeprecatedObjectProxy
+      * DeprecatedInstanceVariableProxy
+      * DeprecatedConstantProxy
+      * deprecation-related test assertions
+
+    Use of `ActiveSupport::Deprecation.silence` and configuration methods like `behavior=`, `disallowed_behavior=`,
+    `disallowed_warnings=` should now be aimed at the [application's deprecators](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-deprecators).
+
+    ```ruby
+    Rails.application.deprecators.silence do
+      # code that emits deprecation warnings
+    end
+    ```
+
+    If your gem has a Railtie or Engine, it's encouraged to add your deprecator to the application's deprecators, that
+    way the deprecation related configuration options will apply to it as well, e.g.
+    `config.active_support.report_deprecations` set to `false` in the production environment will also disable your
+    deprecator.
+
+    ```ruby
+    initializer "my_gem.deprecator" do |app|
+      app.deprecators[:my_gem] = MyGem.deprecator
+    end
+    ```
+
+    *Étienne Barrié*
+
 *   Add `Object#with` to set and restore public attributes around a block
 
     ```ruby

activesupport/lib/active_support/deprecation.rb

@@ -3,8 +3,33 @@
 require "singleton"
 
 module ActiveSupport
-  # \Deprecation specifies the API used by Rails to deprecate methods, instance
-  # variables, objects, and constants.
+  # \Deprecation specifies the API used by Rails to deprecate methods, instance variables, objects, and constants. It's
+  # also available for gems or applications.
+  #
+  # For a gem, use Deprecation.new to create a Deprecation object and store it in your module or class (in order for
+  # users to be able to configure it).
+  #
+  #   module MyLibrary
+  #     def self.deprecator
+  #       @deprecator ||= ActiveSupport::Deprecation.new("2.0", "MyLibrary")
+  #     end
+  #   end
+  #
+  # For a Railtie or Engine, you may also want to add it to the application's deprecators, so that the application's
+  # configuration can be applied to it.
+  #
+  #   module MyLibrary
+  #     class Railtie < Rails::Railtie
+  #       initializer "deprecator" do |app|
+  #         app.deprecators[:my_library] = MyLibrary.deprecator
+  #       end
+  #     end
+  #   end
+  #
+  # With the above initializer, configuration settings like the following will affect +MyLibrary.deprecator+:
+  #
+  #   # in config/environments/test.rb
+  #   config.active_support.deprecation = :raise
   class Deprecation
     # active_support.rb sets an autoload for ActiveSupport::Deprecation.
     #