Document the breaking change in custom resources

Signed-off-by: Tim Smith <tsmith@chef.io>

1 files changed, 29 insertions, 0 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 2d5199703d..259656a864 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -4,6 +4,35 @@ This file holds "in progress" release notes for the current release under develo
 
 ## Breaking Change in Resources
 
+In Chef Infra Client 16.0 we made changes to how the custom resource names are applied in order to resolve some longstanding edge-cases. This change had several unintended side effects so we're further changing how custom names are set in this release of Chef Infra Client.
+
+Previously you could set a custom name for a resource via `resource_name` and under the hood this would also magically set the `provides` for the resource. Magic is great when it works, but is confusing when it doesn't. We've decided to remove some of this magic and instead rely on more explicit provides statements in resources. For cookbooks that support just Chef Infra Client 16 and later you change any `resource_name` calls to `provides` instead. If you need to support older releases of Chef Infra Client as well as 16+ you'll want to include both `resource_name` and `provides` for full compatibility.
+
+**Pre-16 code:**
+
+```ruby
+resource_name :foo
+```
+
+**Chef Infra Client 16+ code**
+
+```ruby
+provides :foo
+```
+
+**Chef Infra Client < 16 backwards compatible code**
+
+```ruby
+resource_name :foo
+provides :foo
+```
+
+We've introduced several Cookstyle rules to detect both custom resources and legacy HWRPs that need to be updated for this change:
+
+**ChefDeprecations/ResourceUsesOnlyResourceName**: detects resources that only set resource_name and automatically adds a provides call as well.
+
+**ChefDeprecations/ResourceWithoutNameOrProvides**: detects legacy HWRPs that don't include the necessary provides and resource_name calls for Chef Infra Client 16.
+
 ## New Resources
 
 ### windows_audit_policy