From 1133e38040e12b20f9193f871ddfe4ca93927f4a Mon Sep 17 00:00:00 2001
From: Elizabeth Kenyon <elizabeth.kenyon@shopify.com>
Date: Mon, 29 Apr 2024 15:32:28 -0500
Subject: [PATCH] Add a migration guide for v.15.0.0

---
 BREAKING_CHANGES_FOR_V15.md | 41 +++++++++++++++++++++++++++++++++++++
 README.md                   |  3 +++
 2 files changed, 44 insertions(+)
 create mode 100644 BREAKING_CHANGES_FOR_V15.md

diff --git a/BREAKING_CHANGES_FOR_V15.md b/BREAKING_CHANGES_FOR_V15.md
new file mode 100644
index 00000000..6d0dd416
--- /dev/null
+++ b/BREAKING_CHANGES_FOR_V15.md
@@ -0,0 +1,41 @@
+# Breaking change notice for version 15.0.0
+
+## Removal of `ShopifyAPI::Webhooks::Handler`
+
+The `ShopifyAPI::Webhooks::Handler` class has been removed in favor of `ShopifyAPI::Webhooks::WebhookHandler`. The `ShopifyAPI::Webhooks::WebhookHandler` class is now the recommended way to handle webhooks.
+
+Make a module or class that includes or extends `ShopifyAPI::Webhooks::WebhookHandler` and implement the `handle` method which accepts the following named parameters: data: `WebhookMetadata`.
+
+
+`data` will have the following keys
+- `topic`, `String` - The topic of the webhook
+- `shop`, `String` - The shop domain of the webhook
+- `body`, `T::Hash[String, T.untyped]`- The body of the webhook
+- `webhook_id`, `String` - The id of the webhook event to [avoid duplicates](https://shopify.dev/docs/apps/webhooks/best-practices#ignore-duplicates)
+- `api_version`, `String` - The api version of the webhook
+
+### New implementation
+```ruby
+module WebhookHandler
+  extend ShopifyAPI::Webhooks::WebhookHandler
+
+  class << self
+    def handle_webhook(data:)
+      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version"
+    end
+  end
+end
+```
+
+### Previous implementation
+```ruby
+module WebhookHandler
+  include ShopifyAPI::Webhooks::Handler
+
+  class << self
+    def handle(topic:, shop:, body:)
+      puts "Received webhook! topic: #{topic} shop: #{shop} body: #{body}"
+    end
+  end
+end
+```
diff --git a/README.md b/README.md
index fbefdc35..8449a265 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,9 @@ Once your app can perform OAuth, it can now make authenticated Shopify API calls
 
 ## Breaking Change Notices
 
+### Breaking change notice for version 15.0.0
+See [BREAKING_CHANGES_FOR_V15](BREAKING_CHANGES_FOR_V15.md)
+
 ### Breaking change notice for version 10.0.0
 See [BREAKING_CHANGES_FOR_V10](BREAKING_CHANGES_FOR_V10.md)