mirrors
/
rails
mirror of https://github.com/rails/rails
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Hartley McGuire 2023-12-14 17:10:44 -05:00
parent 9064735ec5
commit f93eb16564
No known key found for this signature in database
GPG Key ID: E823FC1403858A82
2 changed files with 32 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
activesupport/lib/active_support/deprecation/behaviors.rb
View File

@ -57,15 +57,15 @@ module ActiveSupport
# You can create a custom behavior or set any from the +DEFAULT_BEHAVIORS+ # You can create a custom behavior or set any from the +DEFAULT_BEHAVIORS+
# constant. Available behaviors are: # constant. Available behaviors are:
# #
# [+raise+] Raise ActiveSupport::DeprecationException. # [+:raise+] Raise ActiveSupport::DeprecationException.
# [+stderr+] Log all deprecation warnings to <tt>$stderr</tt>. # [+:stderr+] Log all deprecation warnings to <tt>$stderr</tt>.
# [+log+] Log all deprecation warnings to +Rails.logger+. # [+:log+] Log all deprecation warnings to +Rails.logger+.
# [+notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. # [+:notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+.
# [+report+] Use ActiveSupport::ErrorReporter to report deprecations. # [+:report+] Use ActiveSupport::ErrorReporter to report deprecations.
# [+silence+] Do nothing. On \Rails, set <tt>config.active_support.report_deprecations = false</tt> to disable all behaviors. # [+:silence+] Do nothing. On \Rails, set <tt>config.active_support.report_deprecations = false</tt> to disable all behaviors.
# #
# Setting behaviors only affects deprecations that happen after boot time. # 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 module Behavior
# Whether to print a backtrace along with the warning. # Whether to print a backtrace along with the warning.
attr_accessor :debug attr_accessor :debug
@ -85,12 +85,12 @@ module ActiveSupport
# #
# Available behaviors: # Available behaviors:
# #
# [+raise+] Raise ActiveSupport::DeprecationException. # [+:raise+] Raise ActiveSupport::DeprecationException.
# [+stderr+] Log all deprecation warnings to <tt>$stderr</tt>. # [+:stderr+] Log all deprecation warnings to <tt>$stderr</tt>.
# [+log+] Log all deprecation warnings to +Rails.logger+. # [+:log+] Log all deprecation warnings to +Rails.logger+.
# [+notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+. # [+:notify+] Use ActiveSupport::Notifications to notify +deprecation.rails+.
# [+report+] Use ActiveSupport::ErrorReporter to report deprecations. # [+:report+] Use ActiveSupport::ErrorReporter to report deprecations.
# [+silence+] Do nothing. # [+:silence+] Do nothing.
# #
# Setting behaviors only affects deprecations that happen after boot time. # Setting behaviors only affects deprecations that happen after boot time.
# Deprecation warnings raised by gems are not affected by this setting # Deprecation warnings raised by gems are not affected by this setting
@ -104,15 +104,17 @@ module ActiveSupport
# # custom stuff # # custom stuff
# } # }
# #
# If you are using \Rails, you can set <tt>config.active_support.report_deprecations = false</tt> to disable # If you are using \Rails, you can set
# all deprecation behaviors. This is similar to the +silence+ option but more performant. # <tt>config.active_support.report_deprecations = false</tt> to disable
# all deprecation behaviors. This is similar to the +:silence+ option but
# more performant.
def behavior=(behavior) def behavior=(behavior)
@behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) } @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }
end end
# Sets the behavior for disallowed deprecations (those configured by # Sets the behavior for disallowed deprecations (those configured by
# ActiveSupport::Deprecation#disallowed_warnings=) to the specified # 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+. # object that responds to +call+.
def disallowed_behavior=(behavior) def disallowed_behavior=(behavior)
@disallowed_behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) } @disallowed_behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }

18
guides/source/configuring.md
View File

@ -2537,15 +2537,25 @@ The default value depends on the `config.load_defaults` target version:
#### `config.active_support.deprecation` #### `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` #### `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` #### `config.active_support.disallowed_deprecation_warnings`