Merge pull request #1902 from Shopify/update_docs

Update token exchange and secret rotation documentation

README.md

@@ -169,10 +169,11 @@ ShopifyApp.configure do |config|
 end
 
 ```
-3. Handle special callback logic. If your app has overridden the OAuth CallbackController to run special tasks post authorization, 
+3. Handle special callback logic. If your app has overridden the OAuth CallbackController to run special tasks post authorization,
 you'll need to create and configure a custom PostAuthenticateTasks class to run these tasks after the token exchange. The original
 OAuth CallbackController will not be triggered anymore. See [Post Authenticate Tasks documentation](/docs/shopify_app/authentication.md#post-authenticate-tasks) for more information.
-4. Enjoy a smoother and faster app installation process.
+4. Make sure your `embedded_app` layout is correct. If your app has any controller which includes `ShopifyApp::EnsureInstalled`, they will now also include the `ShopifyApp::EmbeddedApp` concern, which sets `layout 'embedded_app'` for the current controller by default. In cases where the controller originally looked for another layout file, this can cause unexpected behavior. See [`EmbeddedApp` concern's documentation](/docs/shopify_app/controller-concerns.md#embeddedapp) for more information on the effects of this concern and how to disable the layout change if needed.
+5. Enjoy a smoother and faster app installation process.
 
 ### API Versioning
 

docs/shopify_app/authentication.md

@@ -195,6 +195,17 @@ config.secret = Rails.application.secrets.shopify_secret
 config.old_secret = Rails.application.secrets.old_shopify_secret
 ```
 
+Also make sure the old secret is specified when setting up `ShopifyAPI::Context` as well:
+
+```ruby
+ShopifyAPI::Context.setup(
+ api_key: ShopifyApp.configuration.api_key,
+ api_secret_key: ShopifyApp.configuration.secret,
+ # ...
+ old_api_secret_key: ShopifyApp.configuration.old_secret,
+)
+```
+
 We've provided a generator which creates the job and an example rake task:
 
 ```sh