add Chef::Config[:chef_gem_compile_time] plus RELNOTES

* added a config flag to force chef_gem to behave like Chef-10/11
  or to behave like Chef-13.
* added a bunch of release notes to explain the warnings and what to
  do about them in quite a bit of detail.

5 files changed, 127 insertions, 5 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 3c94bf21a9..0de1b26300 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -73,6 +73,54 @@ The `package` provider has been extended to support multiple packages. This
 support is new and and not all subproviders yet support it. Full support for
 `apt` and `yum` has been implemented.
 
+## chef_gem deprecation of installation at compile time
+
+A `compile_time` flag has been added to the chef_gem resource to control if it is installed at compile_time or not.  The prior behavior has been that this
+resource forces itself to install at compile_time which is problematic since if the gem is native it forces build_essentials and other dependent libraries
+to have to be installed at compile_time in an escalating war of forcing compile time execution.  This default was engineered before it was understood that a better
+approach was to lazily require gems inside of provider code which only ran at converge time and that requiring gems in recipe code was bad practice.
+
+The default behavior has not changed, but every chef_gem resource will now emit out a warning:
+
+```
+[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] chef_gem compile_time installation is deprecated
+[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] Please set `compile_time false` on the resource to use the new behavior.
+[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] or set `compile_time true` on the resource if compile_time behavior is required.
+```
+
+The preferred way to fix this is to make every chef_gem resource explicit about compile_time installation (keeping in mind the best-practice to default to false
+unless there is a reason):
+
+```ruby
+chef_gem 'aws-sdk' do
+  compile_time false
+end
+```
+
+There is also a Chef::Config[:chef_gem_compile_time] flag which has been added.  If this is set to true (not recommended) then chef will only emit a single
+warning at the top of the chef-client run:
+
+```
+[2015-02-06T13:27:35-08:00] WARN: setting chef_gem_compile_time to true is deprecated
+```
+
+It will behave like Chef 10 and Chef 11 and will default chef_gem to compile_time installations and will suppress
+subsequent warnings in the chef-client run.
+
+If this setting is changed to 'false' then it will adopt Chef-13 style behavior and will default all chef_gem installs to not run at compile_time by default.  This
+may break existing cookbooks.
+
+All existing cookbooks which require compile_time true MUST be updated to be explicit about this setting.
+All existing cookbooks which do not require compile_time true SHOULD be updated to be explicit about this setting.
+
+For cookbooks that need to maintain backwards compatibility a `respond_to?` check should be used:
+
+```
+chef_gem 'aws-sdk' do
+  compile_time false if respond_to?(:compile_time)
+end
+```
+
 # Chef Client Release Notes 12.0.0:
 
 # Internal API Changes in this Release
diff --git a/lib/chef/application.rb b/lib/chef/application.rb
index 5a67fc9091..00992fdec1 100644
--- a/lib/chef/application.rb
+++ b/lib/chef/application.rb
@@ -49,6 +49,7 @@ class Chef
       configure_logging
       configure_proxy_environment_variables
       configure_encoding
+      emit_warnings
     end
 
     # Get this party started
@@ -372,6 +373,12 @@ class Chef
       ENV
     end
 
+    def emit_warnings
+      if Chef::Config[:chef_gem_compile_time]
+        Chef::Log.warn "setting chef_gem_compile_time to true is deprecated"
+      end
+    end
+
     class << self
       def debug_stacktrace(e)
         message = "#{e.class}: #{e}\n#{e.backtrace.join("\n")}"
diff --git a/lib/chef/config.rb b/lib/chef/config.rb
index 1a4ec06d98..c9e0914c0b 100644
--- a/lib/chef/config.rb
+++ b/lib/chef/config.rb
@@ -627,6 +627,13 @@ class Chef
     #
     default :no_lazy_load, true
 
+    # Default for the chef_gem compile_time attribute.  Nil is the same as false but will emit
+    # warnings on every use of chef_gem prompting the user to be explicit.  If the user sets this to
+    # true then the user will get backcompat behavior but with a single nag warning that cookbooks
+    # may break with this setting in the future.  The false setting is the recommended setting and
+    # will become the default.
+    default :chef_gem_compile_time, nil
+
     # A whitelisted array of attributes you want sent over the wire when node
     # data is saved.
     # The default setting is nil, which collects all data. Setting to [] will not
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 126e3d56c3..c95bf03200 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -28,7 +28,7 @@ class Chef
       def initialize(name, run_context=nil)
         super
         @resource_name = :chef_gem
-        @compile_time = nil
+        @compile_time = Chef::Config[:chef_gem_compile_time]
         @gem_binary = RbConfig::CONFIG['bindir'] + "/gem"
       end
 
@@ -53,9 +53,9 @@ class Chef
         # Chef::Resource.run_action: Caveat: this skips Chef::Runner.run_action, where notifications are handled
         # Action could be an array of symbols, but probably won't (think install + enable for a package)
         if compile_time.nil?
-          Chef::Log.warn "The chef_gem installation at compile time is deprecated and this behavior will change in the future."
-          Chef::Log.warn "Please set `compile_time false` on the resource to use the new behavior and suppress this warning,"
-          Chef::Log.warn "or you may set `compile_time true` on the resource if compile_time behavior is necessary."
+          Chef::Log.warn "#{self} chef_gem compile_time installation is deprecated"
+          Chef::Log.warn "#{self} Please set `compile_time false` on the resource to use the new behavior."
+          Chef::Log.warn "#{self} or set `compile_time true` on the resource if compile_time behavior is required."
         end
 
         if compile_time || compile_time.nil?
diff --git a/spec/unit/resource/chef_gem_spec.rb b/spec/unit/resource/chef_gem_spec.rb
index 657713d54f..18278ba336 100644
--- a/spec/unit/resource/chef_gem_spec.rb
+++ b/spec/unit/resource/chef_gem_spec.rb
@@ -63,7 +63,12 @@ describe Chef::Resource::ChefGem, "gem_binary" do
       Chef::Recipe.new("hjk", "test", run_context)
     end
 
-    let(:resource) { Chef::Resource::ChefGem.new("foo", run_context) }
+    let(:chef_gem_compile_time) { nil }
+
+    let(:resource) do
+      Chef::Config[:chef_gem_compile_time] = chef_gem_compile_time
+      Chef::Resource::ChefGem.new("foo", run_context)
+    end
 
     before do
       expect(Chef::Resource::ChefGem).to receive(:new).and_return(resource)
@@ -97,5 +102,60 @@ describe Chef::Resource::ChefGem, "gem_binary" do
         compile_time false
       end
     end
+
+    describe "when Chef::Config[:chef_gem_compile_time] is explicitly true" do
+      let(:chef_gem_compile_time) { true }
+
+      before do
+        expect(Chef::Log).not_to receive(:warn)
+      end
+
+      it "by default installs at compile-time" do
+        expect(resource).to receive(:run_action).with(:install)
+        recipe.chef_gem "foo"
+      end
+
+      it "compile_time true installs at compile-time" do
+        expect(resource).to receive(:run_action).with(:install)
+        recipe.chef_gem "foo" do
+          compile_time true
+        end
+      end
+
+      it "compile_time false does not install at compile-time" do
+        expect(resource).not_to receive(:run_action).with(:install)
+        recipe.chef_gem "foo" do
+          compile_time false
+        end
+      end
+    end
+
+    describe "when Chef::Config[:chef_gem_compile_time] is explicitly false" do
+
+      let(:chef_gem_compile_time) { false }
+
+      before do
+        expect(Chef::Log).not_to receive(:warn)
+      end
+
+      it "by default does not install at compile-time" do
+        expect(resource).not_to receive(:run_action).with(:install)
+        recipe.chef_gem "foo"
+      end
+
+      it "compile_time true installs at compile-time" do
+        expect(resource).to receive(:run_action).with(:install)
+        recipe.chef_gem "foo" do
+          compile_time true
+        end
+      end
+
+      it "compile_time false does not install at compile-time" do
+        expect(resource).not_to receive(:run_action).with(:install)
+        recipe.chef_gem "foo" do
+          compile_time false
+        end
+      end
+    end
   end
 end