wip

docs/Upgrading.md

@@ -2,38 +2,50 @@
 
 This file documents important changes needed to upgrade your app's Shopify App version to a new major version.
 
-If you are an older version, it is recommended to incrementally upgrade by one major version at a time, and deploy into
-each into production to help detect problems earlier.
+#### Table of contents
 
-# General Notes
+[General Advice](#general-advice)
 
-We strongly recommend you avoid 'monkeypatching' any existing code from `ShopifyApp`, but if your app does so, then you will need to look carefully to check if the underlying implementation has changed.
+[Upgrading to `v19.0.0`](#upgrading-to-v1900)
 
-# Chnages [TODO: check which version these apply to]
+[Upgrading to `v18.1.2`](#upgrading-to-v1812)
 
-- If your app was previously not using App Bridge then you may need to add that.
-- Ensure your jobs inherit from `ApplicationJob`
+[Upgrading to `v17.2.0`](#upgrading-to-v1720)
 
+[Upgrading to `v13.0.0`](#upgrading-to-v1300)
 
-# Important Things to Test
+[Upgrading to `v11.7.0`](#upgrading-to-v1170)
 
-- Webhooks (uninstall your app and ensure the webhooks is triggered)
+[Upgrading from `v8.6` to `v9.0.0`](#upgrading-from-v86-to-v900)
 
-- `current_shopify_domain` is no longer available as a controller method, but you can instead use `current_shopify_session.url`.
+# General Advice
 
-#### Table of contents
+* Although we strive to make upgrades as smooth as possible, the wide variety of uses cases means some effort may be required to stay up to date with the latest changes to `shopify_app`.
+*
+* We strongly recommend you avoid 'monkeypatching' any existing code from `ShopifyApp`, e.g. by inheriting from `ShopifyApp` and then overriding particular methods. This can result in difficult upgrades. If your app does so, you will need carefully check the gem's internal changes.
+* If you need upgrade by more than one major version (e.g. from v18 to v20), we recommend doing so one by major version at a time.
+Deploy each into production will help to detect problems earlier.
+* If you do run into issues, there are two useful techniques to apply: Adding log statements, and using an interactive debugger, such as `pry`.
+* You can temporarily add log statements or debugger calls to the `shopify_app` or `shopify-api-ruby`:
+  * You can modify it using [`bundle open`](https://boringrails.com/tips/bundle-open-debug-gems)
+  * Alternatively, you can your modify your `Gemfile` to use local locally checked out repositories with the the [`path` option](https://bundler.io/man/gemfile.5.html).
+* Note that if you make changes to a gem, you will need to restart the app for the changes to be applied.
 
-[Upgrading to `v19.0.0`](#upgrading-to-v1900)
+# Common Errors
 
-[Upgrading to `v18.1.2`](#upgrading-to-v1812)
+* If you encounter `redirect_uri is not whitelisted`, you likely need to update the App Setup on https://partners.shopify.com/.
 
-[Upgrading to `v17.2.0`](#upgrading-to-v1720)
+# Changes [TODO: check which version these apply to]
 
-[Upgrading to `v13.0.0`](#upgrading-to-v1300)
+- If your app was previously not using App Bridge then you may need to add that.
 
-[Upgrading to `v11.7.0`](#upgrading-to-v1170)
+# Important Things to Test
 
-[Upgrading from `v8.6` to `v9.0.0`](#upgrading-from-v86-to-v900)
+
+
+- Webhooks (uninstall your app and ensure the webhooks is triggered)
+
+- `current_shopify_domain` is no longer available as a controller method, but you can instead use `current_shopify_session.url`.
 
 ## Upgrading to `v19.0.0`
 
@@ -62,6 +74,7 @@ As of v19, since we no longer save the app user to the session (but only the sho
 #### Webhook Jobs
 
 It is assumed that you have an ActiveJob implementation configured for `perform_later`, e.g. Sidekiq.
+Ensure your jobs inherit from `ApplicationJob` or `ActiveJob::Base`.
 
 Add a new `handle` method to existing webhook jobs to go through the updated `shopify_api` gem.