summaryrefslogtreecommitdiff
path: root/DOC_CHANGES.md
diff options
context:
space:
mode:
authorJohn Keiser <john@johnkeiser.com>2015-06-05 11:02:14 -0700
committerJohn Keiser <john@johnkeiser.com>2015-06-08 09:01:54 -0700
commit01f575ce28a55dcdc7b3945c5f49ebb652a1fff3 (patch)
tree49d5c7b74e820ab3736b345e46e40d55551ef6ea /DOC_CHANGES.md
parent8f17f5223727cb9bec3c44b66a3fbe327b7a2f19 (diff)
downloadchef-01f575ce28a55dcdc7b3945c5f49ebb652a1fff3.tar.gz
Fix up doc changes
Diffstat (limited to 'DOC_CHANGES.md')
-rw-r--r--DOC_CHANGES.md54
1 files changed, 43 insertions, 11 deletions
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index cba06a26e6..46712f114c 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -6,27 +6,61 @@ Example Doc Change:
Description of the required change.
-->
-### Resources must now use `resource_name` to declare recipe DSL
+### Resources now *all* get automatic DSL
-Resources declared in `Chef::Resource` namespace will no longer get recipe DSL
-automatically. Instead, `resource_name` is required in order to have DSL:
+When you declare a resource (no matter where) you now get automatic DSL for it, based on your class name:
```ruby
module MyModule
class MyResource < Chef::Resource
- use_automatic_resource_name # Names the resource "my_resource"
+ # Names the resource "my_resource"
end
end
```
-`resource_name :my_resource` may be used to explicitly set the resource name.
+When this happens, the resource can be used in a recipe:
-`provides :my_resource` still works, but at least one resource_name *must* be
-set for the resource to work.
+```ruby
+my_resource 'blah' do
+end
+```
+
+If you have an abstract class that should *not* have DSL, set `resource_name` to `nil`:
+
+```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
+ end
+end
+```
+
+When you do this, `my_base_resource` will not work in a recipe (but `my_resource` will).
+
+You can still use `provides` to provide other DSL names:
-Authors of HWRPs need to be aware that in the future all resources and providers will be required to include a provides line. Starting with Chef 12.4.0 any HWRPs in the `Chef::Resource` or `Chef::Provider` namespaces that do not have provides lines will trigger deprecation warning messages when called. The LWRPBase code does `provides` automatically so LWRP authors and users who write classes that inherit from LWRPBase do not need to explicitly include provides lines.
+```ruby
+module MyModule
+ class MyResource < Chef::Resource
+ provides :super_resource
+ end
+end
+```
-Users are encouraged to declare resources in their own namespaces instead of putting them in the special `Chef::Resource` namespace.
+Which enables this recipe:
+
+```ruby
+super_resource 'wowzers' do
+end
+```
+
+(Note that when you use provides in this manner, resource_name will be `my_resource` and declared_type will be `super_resource`. This won't affect most people, but it is worth noting as a matter of explanation.)
+
+Users are encouraged to declare resources in their own namespaces instead of putting them in the `Chef::Resource` namespace.
### Resources may now use `allowed_actions` and `default_action`
@@ -34,8 +68,6 @@ Instead of overriding `Chef::Resource.initialize` and setting `@allowed_actions`
```ruby
class MyResource < Chef::Resource
- use_automatic_resource_name
-
allowed_actions :create, :delete
default_action :create
end