From f93eb16564281b88342a6993687ca7ad758814be Mon Sep 17 00:00:00 2001 From: Hartley McGuire Date: Thu, 14 Dec 2023 17:10:44 -0500 Subject: [PATCH] Improve Deprecation API docs and guide - Link to Deprecation::Behavior in configuring guide The current list of options for `config.active_support.deprecation` was missing the newly added `:report` option. Instead of adding the missing option and continuing to keep 4 different lists of the same options in sync, I opted to replace the list with a link to the options in the Behavior API docs. This had the additional advantage of giving more information about all of the options which was not mentioned in the Configuring guide. - Use symbols for Behavior options It felt to me like naming the options did not make it explicit that those were the symbols to pass to `#behavior=`, but by adding the `:` that becomes more clear. - Add some API links There were a few references to `behavior=`, but we may as well link to the actual method. --- .../active_support/deprecation/behaviors.rb | 34 ++++++++++--------- guides/source/configuring.md | 18 +++++++--- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/activesupport/lib/active_support/deprecation/behaviors.rb b/activesupport/lib/active_support/deprecation/behaviors.rb index bbeb06cedd2..2473263fcf9 100644 --- a/activesupport/lib/active_support/deprecation/behaviors.rb +++ b/activesupport/lib/active_support/deprecation/behaviors.rb @@ -57,15 +57,15 @@ module ActiveSupport # You can create a custom behavior or set any from the +DEFAULT_BEHAVIORS+ # constant. Available behaviors are: # - # [+raise+] Raise ActiveSupport::DeprecationException. - # [+stderr+] Log all deprecation warnings to $stderr. - # [+log+] Log all deprecation warnings to +Rails.logger+. - # [+notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. - # [+report+] Use ActiveSupport::ErrorReporter to report deprecations. - # [+silence+] Do nothing. On \Rails, set config.active_support.report_deprecations = false to disable all behaviors. + # [+:raise+] Raise ActiveSupport::DeprecationException. + # [+:stderr+] Log all deprecation warnings to $stderr. + # [+:log+] Log all deprecation warnings to +Rails.logger+. + # [+:notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. + # [+:report+] Use ActiveSupport::ErrorReporter to report deprecations. + # [+:silence+] Do nothing. On \Rails, set config.active_support.report_deprecations = false to disable all behaviors. # # Setting behaviors only affects deprecations that happen after boot time. - # For more information you can read the documentation of the +behavior=+ method. + # For more information you can read the documentation of the #behavior= method. module Behavior # Whether to print a backtrace along with the warning. attr_accessor :debug @@ -85,12 +85,12 @@ module ActiveSupport # # Available behaviors: # - # [+raise+] Raise ActiveSupport::DeprecationException. - # [+stderr+] Log all deprecation warnings to $stderr. - # [+log+] Log all deprecation warnings to +Rails.logger+. - # [+notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. - # [+report+] Use ActiveSupport::ErrorReporter to report deprecations. - # [+silence+] Do nothing. + # [+:raise+] Raise ActiveSupport::DeprecationException. + # [+:stderr+] Log all deprecation warnings to $stderr. + # [+:log+] Log all deprecation warnings to +Rails.logger+. + # [+:notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. + # [+:report+] Use ActiveSupport::ErrorReporter to report deprecations. + # [+:silence+] Do nothing. # # Setting behaviors only affects deprecations that happen after boot time. # Deprecation warnings raised by gems are not affected by this setting @@ -104,15 +104,17 @@ module ActiveSupport # # custom stuff # } # - # If you are using \Rails, you can set config.active_support.report_deprecations = false to disable - # all deprecation behaviors. This is similar to the +silence+ option but more performant. + # If you are using \Rails, you can set + # config.active_support.report_deprecations = false to disable + # all deprecation behaviors. This is similar to the +:silence+ option but + # more performant. def behavior=(behavior) @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) } end # Sets the behavior for disallowed deprecations (those configured by # ActiveSupport::Deprecation#disallowed_warnings=) to the specified - # value. As with +behavior=+, this can be a single value, array, or an + # value. As with #behavior=, this can be a single value, array, or an # object that responds to +call+. def disallowed_behavior=(behavior) @disallowed_behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) } diff --git a/guides/source/configuring.md b/guides/source/configuring.md index a6f69841139..1d155af82d5 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -2537,15 +2537,25 @@ The default value depends on the `config.load_defaults` target version: #### `config.active_support.deprecation` -Configures the behavior of deprecation warnings. The options are `:raise`, `:stderr`, `:log`, `:notify`, and `:silence`. +Configures the behavior of deprecation warnings. See +[`Deprecation::Behavior`][deprecation_behavior] for a description of the +available options. -In the default generated `config/environments` files, this is set to `:log` for development and `:stderr` for test, and it is omitted for production in favor of [`config.active_support.report_deprecations`](#config-active-support-report-deprecations). +In the default generated `config/environments` files, this is set to `:log` for +development and `:stderr` for test, and it is omitted for production in favor of +[`config.active_support.report_deprecations`](#config-active-support-report-deprecations). + +[deprecation_behavior]: https://api.rubyonrails.org/classes/ActiveSupport/Deprecation/Behavior.html#method-i-behavior-3D #### `config.active_support.disallowed_deprecation` -Configures the behavior of disallowed deprecation warnings. The options are `:raise`, `:stderr`, `:log`, `:notify`, and `:silence`. +Configures the behavior of disallowed deprecation warnings. See +[`Deprecation::Behavior`][deprecation_behavior] for a description of the +available options. -In the default generated `config/environments` files, this is set to `:raise` for both development and test, and it is omitted for production in favor of [`config.active_support.report_deprecations`](#config-active-support-report-deprecations). +In the default generated `config/environments` files, this is set to `:raise` +for both development and test, and it is omitted for production in favor of +[`config.active_support.report_deprecations`](#config-active-support-report-deprecations). #### `config.active_support.disallowed_deprecation_warnings`