docs: added an upgrade guide for v1.7.1 (#2868)

* docs: added an upgrade guide for 1.7.1

* docs: added more required changes for the release

* docs: removed link to payment provider docs

* docs: reordered upgrade guides in desc order

* added export to code snippet

* added details about update_request property

* fixed the text

* added link to scheduled jobs docs

docs/content/advanced/backend/upgrade-guides/1-7-1.md

@@ -0,0 +1,115 @@
+---
+description: 'Actions Required for v.1.7.1'
+---
+
+# v1.7.1
+
+Version `1.7.1` of Medusa introduces the `JobSchedulerService` which changes how scheduled/cron jobs are created.
+
+## Overview
+
+Version `1.7.1` of Medusa introduces a new service `JobSchedulerService` that handles all logic and functionality related to created scheduled (previously named cron jobs).
+
+With this introduction, the previous use of `EventBus` to create a cron job has been deprecated of using the `JobSchedulerService`.
+
+In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented.
+
+## Actions Required
+
+### Run Migrations
+
+In the directory of your Medusa server, run the following command after updating the server:
+
+```bash
+medusa migrations run
+```
+
+### Run Migration Script
+
+Following the fix gift cards calculation, you also need to run a migration script after updating the server.
+
+Start by adding the following environment variables in `.env`:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_USERNAME=<DATABASE_USERNAME>
+TYPEORM_PASSWORD=<DATABASE_PASSWORD>
+TYPEORM_DATABASE=<DATABASE_DATABASE>
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+Make sure to replace `<DATABASE_URL>`, `<DATABASE_USERNAME>`, `<DATABASE_PASSWORD>`, and `<DATABASE_DATABASE>` with your database connection details.
+
+Then, run the following command in the root directory of your Medusa server:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/gift-card-tax-rate-migration.js
+```
+
+### Change to JobSchedulerService
+
+In your loader file that creates a cron job, replace the use of `eventBus` to `jobSchedulerService`:
+
+```ts
+const myJob = async (container, options) => {
+  const jobSchedulerService = container.resolve("jobSchedulerService");
+  jobSchedulerService.create("my-job", {}, "0 0 * * *", async () => {
+    //...
+  });
+}
+
+export default myJob;
+```
+
+You can learn more in the [How to Create a Scheduled Job](../scheduled-jobs/create.md) documentation.
+
+### Change to Payment Provider
+
+This version of Medusa introduces a change in how payment providers are implemented. Mainly, the signature of the `createPayment` and `updatePayment` methods have changed, and the old signature is now deprecated.
+
+Although this change is currently backwards compatible, it is recommended to change the signature of these methods to the following:
+
+```ts
+import { PaymentContext, PaymentSessionResponse } from '@medusajs/medusa'
+
+async createPayment(context: PaymentContext): Promise<PaymentSessionResponse> {
+  //...
+}
+
+async updatePayment(paymentSessionData: PaymentSessionData, context: PaymentContext): Promise<PaymentSessionResponse> {
+  //...
+}
+```
+
+Where `context` in both `createPayment` and `updatePayment` is made up of the following properties:
+
+```ts
+type PaymentContext = {
+  cart: {
+    context: Record<string, unknown>
+    id: string
+    email: string
+    shipping_address: Address | null
+    shipping_methods: ShippingMethod[]
+  }
+  currency_code: string
+  amount: number
+  resource_id?: string
+  customer?: Customer
+}
+```
+
+So, you can pass the previous `cart` parameter inside the new `context` paramter.
+
+Furthermore, these methods are now expected to return `PaymentSessionResponse`. It is made up of the following properties:
+
+```ts
+type PaymentSessionResponse = {
+  update_requests: { customer_metadata: Record<string, unknown> }
+  session_data: Record<string, unknown>
+}
+```
+
+Where `session_data` would include the previously returned data from these methods. The property `update_requests` allows you to pass data from the payment provider plugin to the core to update internal resources. Currently, it can only be used to update the `metadata` field of the customer entity.

www/docs/sidebars.js

@@ -176,18 +176,13 @@ module.exports = {
           items: [
             {
               type: "doc",
-              id: "advanced/backend/upgrade-guides/1-3-0",
+              id: "advanced/backend/upgrade-guides/1-7-1",
-              label: "v1.3.0"
+              label: "v1.7.1"
             },
             {
               type: "doc",
-              id: "advanced/backend/upgrade-guides/1-3-6",
+              id: "advanced/backend/upgrade-guides/1-7-0",
-              label: "v1.3.6"
+              label: "v1.7.0"
-            },
-            {
-              type: "doc",
-              id: "advanced/backend/upgrade-guides/1-3-8",
-              label: "v1.3.8"
             },
             {
               type: "doc",
@@ -196,8 +191,18 @@ module.exports = {
             },
             {
               type: "doc",
-              id: "advanced/backend/upgrade-guides/1-7-0",
+              id: "advanced/backend/upgrade-guides/1-3-8",
-              label: "v1.7.0"
+              label: "v1.3.8"
+            },
+            {
+              type: "doc",
+              id: "advanced/backend/upgrade-guides/1-3-6",
+              label: "v1.3.6"
+            },
+            {
+              type: "doc",
+              id: "advanced/backend/upgrade-guides/1-3-0",
+              label: "v1.3.0"
             },
             {
               type: "doc",