Add method_missing and DSL deprecation to docs

1 files changed, 33 insertions, 0 deletions

diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 6b58871418..70f62ed629 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -5,3 +5,36 @@ Example Doc Change:
 ### Headline for the required change
 Description of the required change.
 -->
+
+### Resources must now use `provides` to declare recipe DSL
+
+Resources declared in `Chef::Resource` namespace will no longer get recipe DSL
+automatically.  Instead, explicit `provides` is required in order to have DSL:
+
+```ruby
+module MyModule
+  class MyResource < Chef::Resource
+    provides :my_resource
+  end
+end
+```
+
+Users are encouraged to declare resources in their own namespaces.
+
+This is deprecated (and will emit a warning) in Chef 12, and will be removed in
+Chef 13.
+
+### LWRPs are no longer placed in the `Chef::Resource` namespace
+
+Additionally, resources declared as LWRPs are no longer placed in the
+`Chef::Resource` namespace.  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`.
+
+You can still get the LWRP class by calling `Chef::Resource.resource_matching_short_name(:mycookbook_myresource)`.
+
+The primary aim here is clearing out the `Chef::Resource` namespace.
+
+References to these classes is deprecated (and will emit a warning) in Chef 12, and will be removed in Chef 13.