Merge pull request #7375 from coderanger/silence-deprecations

Silence deprecation warnings

RELEASE_NOTES.md

@@ -1,5 +1,54 @@
 This file holds "in progress" release notes for the current release under development and is intended for consumption by the Chef Documentation team. Please see <https://docs.chef.io/release_notes.html> for the official Chef release notes.
 
+## Silencing deprecation warnings
+
+While deprecation warnings have been great for the Chef community to ensure
+cookbooks are kept up-to-date and to prepare for major version upgrades, sometimes
+you just can't fix a deprecation right now. This is often compounded by the
+recommendation to enable `treat_deprecation_warnings_as_errors` mode in your
+Test Kitchen integration tests, which doesn't understand the difference between
+deprecations from community cookbooks and those from your own code.
+
+Two new options are provided for silencing deprecation warnings: `silence_deprecation_warnings`
+and inline `chef:silence_deprecation` comments.
+
+The `silence_deprecation_warnings` configuration value can be set in your
+`client.rb` or `solo.rb` config file, either to `true` to silence all deprecation
+warnings or to an array of deprecations to silence. You can specify which to
+silence either by the deprecation key name (e.g. `"internal_api"`), the numeric
+deprecation ID (e.g. `25` or `"CHEF-25"`), or by specifying the filename and
+line number where the deprecation is being raised from (e.g. `"default.rb:67"`).
+
+An example of setting the `silence_deprecation_warnings` option in your `client.rb`
+or `solo.rb`:
+
+```ruby
+silence_deprecation_warnings %w{deploy_resource chef-23 recipes/install.rb:22}
+```
+
+or in your `kitchen.yml`:
+
+```yaml
+provisioner:
+  name: chef_solo
+  solo_rb:
+    treat_deprecation_warnings_as_errors: true
+    silence_deprecation_warnings:
+    - deploy_resource
+    - chef-23
+    - recipes/install.rb:22
+```
+
+You can also silence deprecations using a comment on the line that is raising
+the warning:
+
+```ruby
+erl_call 'something' do # chef:silence_deprecation
+```
+
+We advise caution in the use of this feature, as excessive or prolonged silencing
+can lead to difficulty upgrading when the next major release of Chef comes out.
+
 # Chef Client Release Notes 14.2:
 
 ## `ssh-agent` support for user keys

chef-config/lib/chef-config/config.rb

@@ -715,6 +715,11 @@ def self.init_openssl
       ENV.key?("CHEF_TREAT_DEPRECATION_WARNINGS_AS_ERRORS")
     end
 
+    # Which deprecations warnings to silence. Can be set to `true` to silence
+    # all warnings, or an array of strings like either `"deprecation_type"` or
+    # `"filename.rb:lineno"`.
+    default :silence_deprecation_warnings, []
+
     # Whether the resource count should be updated for log resource
     # on running chef-client
     default :count_log_resource_updates, true

lib/chef/chef_class.rb

@@ -200,13 +200,14 @@ def resource_handler_map
     #
     # Emit a deprecation message.
     #
-    # @param [Symbol] type The message to send. This should refer to a class
+    # @param type [Symbol] The message to send. This should refer to a class
     #   defined in Chef::Deprecated
-    # @param message  An explicit message to display, rather than the generic one
-    #   associated with the deprecation.
-    # @param location The location. Defaults to the caller who called you (since
-    #   generally the person who triggered the check is the one that needs to be
-    #   fixed).
+    # @param message [String, nil] An explicit message to display, rather than
+    #   the generic one associated with the deprecation.
+    # @param location [String, nil] The location. Defaults to the caller who
+    #   called you (since generally the person who triggered the check is the one
+    #   that needs to be fixed).
+    # @return [void]
     #
     # @example
     #     Chef.deprecated(:my_deprecation, message: "This is deprecated!")
@@ -220,11 +221,18 @@ def deprecated(type, message, location = nil)
       # run. If we are not yet in a run, print to `Chef::Log`.
       if run_context && run_context.events
         run_context.events.deprecation(deprecation, location)
-      else
-        Chef::Log.deprecation(deprecation, location)
+      elsif !deprecation.silenced?
+        Chef::Log.deprecation(deprecation.to_s)
       end
     end
 
+    # Log a generic deprecation warning that doesn't have a specific class in
+    # Chef::Deprecated.
+    #
+    # This should generally not be used, as the user will not be given a link
+    # to get more infomration on fixing the deprecation warning.
+    #
+    # @see #deprecated
     def log_deprecation(message, location = nil)
       location ||= Chef::Log.caller_location
       Chef.deprecated(:generic, message, location)