Add method_missing and DSL deprecation to docs

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Unreleased
 
+* [pr#3269](https://github.com/chef/chef/pull/3269): Deprecate automatic recipe
+  DSL for classes in `Chef::Resource`
 * [pr#3160](https://github.com/chef/chef/pull/3160): Use Chef Zero in
   socketless mode for local mode, add `--no-listen` flag to disable port
   binding
@@ -34,14 +36,14 @@
 
 ## 12.1.2
 * [Issue 3022](https://github.com/chef/chef/issues/3022): Homebrew Cask install fails
-  FIXME (remove on 12.2.0 release): 3022 was only merged to 12-stable and #3077 or its descendant should fix this 
+  FIXME (remove on 12.2.0 release): 3022 was only merged to 12-stable and #3077 or its descendant should fix this
 * [Issue 3059](https://github.com/chef/chef/issues/3059): Chef 12.1.1 yum_package silently fails
 * [Issue 3078](https://github.com/chef/chef/issues/3078): Compat break in audit-mode changes
 
 ## 12.1.1
 * [**Phil Dibowitz**](https://github.com/jaymzh):
   [Issue 3008](https://github.com/chef/chef/issues/3008) Allow people to pass in `source` to package
-* [Issue 3011](https://github.com/chef/chef/issues/3011) `package` provider base should include 
+* [Issue 3011](https://github.com/chef/chef/issues/3011) `package` provider base should include
   `Chef::Mixin::Command` as there are still providers that use it.
 * [**Ranjib Dey**](https://github.com/ranjib):
   [Issue 3019](https://github.com/chef/chef/issues/3019) Fix data fetching when explicit attributes are passed

DOC_CHANGES.md

@@ -6,6 +6,39 @@ Example Doc 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.
+
 ### Chef Client and Knife `--no-listen` Flag and `listen` Config Option
 
 Chef Client and Knife have a `--no-listen` CLI option. It is only