Merge pull request #3578 from chef/jk/doc_changesjdm/12.4.0.rc.3

Add some doc changes for 12.4.0

1 files changed, 73 insertions, 10 deletions

diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 46712f114c..bf0f197cd5 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -6,13 +6,14 @@ Example Doc Change:
 Description of the required change.
 -->
 
-### Resources now *all* get automatic DSL
+### Resources may now specify `resource_name` to get DSL
 
-When you declare a resource (no matter where) you now get automatic DSL for it, based on your class name:
+When you declare a resource class, you may call `resource_name` to get recipe DSL for it.
 
 ```ruby
 module MyModule
   class MyResource < Chef::Resource
+    resource_name :my_resource
     # Names the resource "my_resource"
   end
 end
@@ -25,16 +26,18 @@ my_resource 'blah' do
 end
 ```
 
-If you have an abstract class that should *not* have DSL, set `resource_name` to `nil`:
+If you have an abstract class that should *not* have DSL, you may set `resource_name` to `nil` (this is only really important for classes in `Chef::Resource` which get DSL automatically):
 
 ```ruby
-module MyModule
-  # This will not have DSL
-  class MyBaseResource < Chef::Resource
-    resource_name nil
-  end
-  # This will have DSL `my_resource`
-  class MyResource < MyBaseResource
+class Chef
+  class Resource
+    # This will not have DSL
+    class MyBaseResource < Chef::Resource
+      resource_name nil
+    end
+    # This will have DSL `my_resource`
+    class MyResource < MyBaseResource
+    end
   end
 end
 ```
@@ -73,6 +76,66 @@ class MyResource < Chef::Resource
 end
 ```
 
+### Resource `provides` now has intuitive automatic rules
+
+`provides` is how a Resource or Provider associates itself with the Chef recipe DSL on different OS's.  Now when multiple resources or providers say they provide the same DSL, "specificity rules" are applied to decide the priority of these rules.  For example:
+
+```ruby
+class GenericFile < Chef::Resource
+  provides :file
+end
+class LinuxFile < Chef::Resource
+  provides :file, os: 'linux'
+end
+class DebianFile < Chef::Resource
+  provides :file, platform_family: 'debian'
+end
+```
+
+This means that if I run this recipe on Ubuntu, it will pick DebianFile:
+
+```ruby
+file 'x' do
+end
+```
+
+Now, no matter what order those resources are declared in, the resource lookup system will choose DebianFile on Debian-based platforms since that is the most specific rule.  If a platform is Linux but *not* Debian, like Red Hat, it will pick LinuxFile, since that is less specific.
+
+The specificity order (from highest to lowest) is:
+
+1. provides :x, platform_version: '12.4.0'
+2. provides :x, platform: 'ubuntu'
+3. provides :x, platform_family: 'debian'
+4. provides :x, os: 'linux'
+5. provides :x
+
+This means that a class that specifies a platform_version will *always* be picked over any other provides line.
+
+### Warnings when multiple classes try to provide the same resource DSL
+
+We now warn you when you are replacing DSL provided by another resource or
+provider class:
+
+```ruby
+class X < Chef::Resource
+  provides :file
+end
+class Y < Chef::Resource
+  provides :file
+end
+```
+
+This will emit a warning that Y is overriding X.  To disable the warning, use `override: true`:
+
+```ruby
+class X < Chef::Resource
+  provides :file
+end
+class Y < Chef::Resource
+  provides :file, override: true
+end
+```
+
 ### LWRPs are no longer automatically placed in the `Chef::Resource` namespace
 
 Starting with Chef 12.4.0, accessing an LWRP class by name from the `Chef::Resource` namespace will trigger a deprecation warning message. This means that if your cookbook includes the LWRP `mycookbook/resources/myresource.rb`, you will no longer be able to extend or reference `Chef::Resource::MycookbookMyresource` in Ruby code.  LWRP recipe DSL does not change: the LWRP will still be available to recipes as `mycookbook_myresource`.