Tracks known ActiveSupport (Rails) deprecation warnings and catches new issues when an unknown warning is seen.
This allows for easier upgrades of Rails and other AS-based apps because as each deprecation warning is fixed, it's removed from the whitelist and any attempt to reintroduce the deprecated call will fail. It's also useful when the app runs on multiple versions of Rails and newer deprecation warnings can't be fixed yet without breaking the older version.
The library maintains the whitelist in a configuration file that's usually initially written by running the app test suite with an environment variable set. When the tests are run normally, deprecation warnings triggered that aren't in the config file will raise an exception. The call can then be fixed or added to the whitelist with the provided instructions.
If you'd prefer just to fix all deprecation warnings at once then this gem is unnecessary! Just use:
ActiveSupport::Deprecation.behavior = :raise
in your test environment config.
$ gem install as_deprecation_tracker
or in your Gemfile:
gem 'as_deprecation_tracker', '~> 1.0', group: 'test'
This gem and its API is versioned according to semver.
It's recommended to only add the gem to the test Bundler group as raising errors in production and development isn't desirable.
To set up an initial whitelist, run:
AS_DEPRECATION_RECORD=yes bin/rake test
This will generate config/as_deprecation_whitelist.yaml
with a list of
specific instances of deprecated calls which can be committed. Subsequent rake test
runs will then automatically raise errors for new occurrences.
Re-run tests with AS_DEPRECATION_RECORD=yes
to append new instances to the
existing whitelist file, if you wish to permit rather than fix them.
Use AS_DEPRECATION_WHITELIST=~/rails_engine
to set a different root directory
or whitelist file to update, e.g. for a Rails engine.
The whitelist may be broad, permitting any call causing a particular deprecation message or be precise, only permitting known calls identified by their backtrace. With broad whitelists, more instances of the same deprecated call may be added, but precise whitelists require more maintenance if code is moved and the backtrace changes.
The whitelist is stored in the Rails root at
config/as_deprecation_whitelist.yaml
and is a YAML file containing a single
array of hashes:
---
- message: "Deprecated call to X, use Y instead"
- message: "Deprecated call to Z"
callstack: "app/models/foo.rb:23:in `example_method'"
Accepted keys are:
message
, matching the exact deprecation messagecallstack
, a string or an array forming the backtrace of the deprecation. If an array is given for the callstack, all entries must match the caller.engine
, a Railsengine_name
string, matching any call within the engine
The callstack will match on as much data as is provided - if only a file is
given, any matching deprecation within the file will be whitelisted. The line
number and method specification may be given for more specificity. The line
number may vary by up to ten lines from the recorded number by default (see
line_tolerance
to tune). Usually the filename and method name are sufficient
to match the caller without needing line numbers.
The message is an exact string match on the start of the deprecation message, so not all of the original deprecation message needs to be specified.
Additional whitelist files may be placed below the root of each Rails engine and will be loaded at startup in addition to the main Rails root config file.
Entries can be added programmatically by calling
ASDeprecationTracker.whitelist.add(message: ...)
with any of the supported
keys above supplied as keyword arguments.
Use an initializer to change ASDT's behaviour at startup:
ASDeprecationTracker.config.envs = %w(test development)
Supported options:
envs
is an array of string Rails environment names that ASDT will monitor and raise errors for unpermitted deprecation warnings (defaults to['test']
)line_tolerance
is the number of lines that callstack line numbers may differ from the deprecated call (defaults to 10)register_behavior
controls whether to change the AS::Deprecation behavior to ASDeprecationTracker::Receiver at startup, may be disabled to use multiple behaviors (defaults to true)whitelist_file
to customise the location of the whitelist YAML file (defaults toconfig/as_deprecation_whitelist.yaml
)
Both AS_DEPRECATION_
or the shorter ASDT_
prefixes work with all
environment variables listed below.
AS_DEPRECATION_DISABLE
- set to any value will prevent ASDT from monitoring deprecations and throwing exceptions. Rails will use default deprecation behaviour.AS_DEPRECATION_RECORD
- set to any value will prevent ASDT from throwing exceptions and will append entries to thewhitelist_file
for every deprecation seen.AS_DEPRECATION_WHITELIST
- set to the root or full path of a whitelist configuration file, overrideswhitelist_file
.
The processing of deprecation warnings can be suspended and resumed via the
ASDeprecationTracker.pause!
and ASDeprecationTracker.resume!
methods.
This is useful when programmatically building whitelist entries during Rails
initialisation, as deprecation processing can be disabled until the whitelist
is fully formed. ASDT will queue events while paused and processes them when
resume!
is called.
Shopify have open-sourced a gem that works very similarly to ASDT and is worth
a look. It supports more configuration options when seeing a new or removed
deprecation warning, and also supports Kernel#warn
.
Copyright (c) 2016-2022 Dominic Cleal. Distributed under the MIT license.