diff --git a/www/apps/book/app/learn/installation/page.mdx b/www/apps/book/app/learn/installation/page.mdx
index 5ad1384794..f7c21dffc6 100644
--- a/www/apps/book/app/learn/installation/page.mdx
+++ b/www/apps/book/app/learn/installation/page.mdx
@@ -105,18 +105,6 @@ You can then use the user's credentials to log into the Medusa Admin application
---
-## Update Medusa Application
-
-New Medusa updates are posted in the [GitHub repository's releases](https://github.com/medusajs/medusa/releases). You can also find the latest version at the top navigation of the documentation, and you can click on it to view the release notes of the latest version.
-
-To update your Medusa application, bump the version of all `@medusajs/*` dependencies in your `package.json`. Then, re-install dependencies:
-
-```bash npm2yarn
-npm run install
-```
-
----
-
## Project Files
Your Medusa application's project will have the following files and directories:
diff --git a/www/apps/book/app/learn/update/page.mdx b/www/apps/book/app/learn/update/page.mdx
new file mode 100644
index 0000000000..cc90847bfb
--- /dev/null
+++ b/www/apps/book/app/learn/update/page.mdx
@@ -0,0 +1,110 @@
+import { config } from "../../../config/index"
+
+export const metadata = {
+ title: `${pageNumber} Updating Medusa`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn about updating your Medusa application and packages.
+
+export const releaseNoteText = `Read the [Release Notes](${config.version.releaseUrl}).`
+
+
+
+Medusa's current version is v{config.version.number}. {releaseNoteText}
+
+
+
+## Medusa Versioning
+
+When Medusa puts out a new release, all packages are updated to the same version. This ensures that all packages are compatible with each other, and makes it easier for you to switch between versions.
+
+
+
+This doesn't apply to the design-system packages, including `@medusajs/ui`, `@medusajs/ui-presets`, and `@medusajs/ui-icons`. These packages are versioned independently. However, you don't need to install and manage them separately in your Medusa application, as they are included in the `@medusajs/admin-sdk`. If you're using them in a standalone project, such as a storefront or custom admin dashboard, refer to [this section in the Medusa UI documentation](!ui!/installation/standalone-project#updating-ui-packages) for update instructions.
+
+
+
+Medusa updates the version number `major.minor.patch` according to the following rules:
+
+- **patch**: A patch release includes bug fixes and minor improvements. It doesn't include breaking changes. For example, if the current version is `2.0.0`, the next patch release will be `2.0.1`.
+- **minor**: A minor release includes new features, fixes, improvements, and breaking changes. For example, if the current version is `2.0.0`, the next minor release will be `2.1.0`.
+- **major**: A major release includes significant changes to the entire codebase and architecture. For those, the update process will be more elaborate. For example, if the current version is `2.0.0`, the next major release would be `3.0.0`.
+
+---
+
+## Check Installed Version
+
+To check the currently installed version of Medusa in your project, run the following command in your Medusa application:
+
+```bash
+npx medusa -v
+```
+
+This will show you the installed version of Medusa and the [Medusa CLI tool](!resources!/medusa-cli), which should be the same.
+
+---
+
+## Check Latest Version
+
+The documentation shows the current version at the top right of the navigation bar. When a new version is released, you'll find a blue dot on the version number. Clicking it will take you to the [release notes on GitHub](https://github.com/medusajs/medusa/releases).
+
+You can also star the [Medusa repository on GitHub](https://github.com/medusajs/medusa) to receive updates about new releases on your GitHub dashboard. Our team also shares updates on new releases on our social media channels.
+
+---
+
+## Update Medusa Application
+
+Before updating a Medusa application, make sure to check the [release notes](https://github.com/medusajs/medusa/releases) for any breaking changes that require actions from your side.
+
+Then, to update your Medusa application, bump the version of all `@medusajs/*` dependencies in your `package.json`. Then, re-install dependencies:
+
+```bash npm2yarn
+npm run install
+```
+
+This will update all Medusa packages to the latest version.
+
+### Running Migrations
+
+Releases may include changes to the database, such as new tables, updates to existing tables, updates after adding links, or data migration scripts.
+
+So, after updating Medusa, run the following command to migrate the latest changes to your database:
+
+```bash
+npx medusa db:migrate
+```
+
+This will run all pending migrations, sync links, and run data migration scripts.
+
+### Reverting an Update
+
+Before reverting an update, if you already ran the migrations, you have to first identify the modules who had migrations. Then, before reverting, run the `db:rollback` command for each of those modules.
+
+For example, if the version you updated to had migrations for the Cart and Product Modules, run the following command:
+
+```bash
+npx medusa db:rollback cart product
+```
+
+Then, revert the update by changing the version of all `@medusajs/*` dependencies in your `package.json` to the previous version and re-installing dependencies:
+
+```bash npm2yarn
+npm run install
+```
+
+Finally, run the migrations to sync link changes:
+
+```bash
+npx medusa db:migrate
+```
+
+---
+
+## Understanding Codebase Changes
+
+In the Medusa codebase, our team uses the following [TSDoc](https://tsdoc.org/) tags to indicate changes made in the latest version for a specific piece of code:
+
+- `@deprecated`: Indicates that a piece of code is deprecated and will be removed in a future version. The tag's message will include details on what to use instead. However, our updates are always backward-compatible, allowing you to update your codebase at your own pace.
+- `@version`: Indicates the version when a piece of code was available from. A piece of code that has this tag will only be available starting from the specified version.
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index c7a90f86e6..5fd0223d13 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -109,5 +109,6 @@ export const generatedEditDates = {
"app/learn/installation/page.mdx": "2025-01-06T09:12:48.690Z",
"app/learn/fundamentals/data-models/check-constraints/page.mdx": "2024-12-06T14:34:50.384Z",
"app/learn/fundamentals/module-links/link/page.mdx": "2025-01-06T09:27:25.604Z",
- "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-01-24T12:09:24.087Z"
+ "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-01-24T12:09:24.087Z",
+ "app/learn/update/page.mdx": "2025-01-24T17:35:21.335Z"
}
\ No newline at end of file
diff --git a/www/apps/book/generated/sidebar.mjs b/www/apps/book/generated/sidebar.mjs
index ff0ce9c7bf..5cb8fae62e 100644
--- a/www/apps/book/generated/sidebar.mjs
+++ b/www/apps/book/generated/sidebar.mjs
@@ -660,6 +660,15 @@ export const generatedSidebar = [
"children": [],
"chapterTitle": "3.6.10. Workflow Timeout"
},
+ {
+ "loaded": true,
+ "isPathHref": true,
+ "type": "link",
+ "path": "/learn/fundamentals/workflows/store-executions",
+ "title": "Store Workflow Executions",
+ "children": [],
+ "chapterTitle": "3.6.11. Store Workflow Executions"
+ },
{
"loaded": true,
"isPathHref": true,
@@ -667,7 +676,7 @@ export const generatedSidebar = [
"path": "/learn/fundamentals/workflows/long-running-workflow",
"title": "Long-Running Workflow",
"children": [],
- "chapterTitle": "3.6.11. Long-Running Workflow"
+ "chapterTitle": "3.6.12. Long-Running Workflow"
},
{
"loaded": true,
@@ -676,7 +685,7 @@ export const generatedSidebar = [
"path": "/learn/fundamentals/workflows/execute-another-workflow",
"title": "Execute Another Workflow",
"children": [],
- "chapterTitle": "3.6.12. Execute Another Workflow"
+ "chapterTitle": "3.6.13. Execute Another Workflow"
},
{
"loaded": true,
@@ -685,7 +694,7 @@ export const generatedSidebar = [
"path": "/learn/fundamentals/workflows/multiple-step-usage",
"title": "Multiple Step Usage",
"children": [],
- "chapterTitle": "3.6.13. Multiple Step Usage"
+ "chapterTitle": "3.6.14. Multiple Step Usage"
}
],
"chapterTitle": "3.6. Workflows"
@@ -964,7 +973,25 @@ export const generatedSidebar = [
},
{
"type": "category",
- "title": "7. More Resources",
+ "title": "7. Updates",
+ "children": [
+ {
+ "loaded": true,
+ "isPathHref": true,
+ "type": "link",
+ "path": "/learn/update",
+ "title": "Updating Medusa",
+ "chapterTitle": "7. Updates",
+ "children": [],
+ "childrenSameLevel": true
+ }
+ ],
+ "loaded": true,
+ "initialOpen": false
+ },
+ {
+ "type": "category",
+ "title": "8. More Resources",
"children": [
{
"loaded": true,
@@ -974,7 +1001,7 @@ export const generatedSidebar = [
"title": "More Resources",
"children": [],
"childrenSameLevel": true,
- "chapterTitle": "7. More Resources"
+ "chapterTitle": "8. More Resources"
}
],
"loaded": true,
diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs
index 968a96d77e..2a244615d6 100644
--- a/www/apps/book/sidebar.mjs
+++ b/www/apps/book/sidebar.mjs
@@ -553,6 +553,12 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
],
},
+ {
+ type: "link",
+ path: "/learn/update",
+ title: "Updating Medusa",
+ chapterTitle: "Updates",
+ },
{
type: "link",
path: "/learn/more-resources",
diff --git a/www/apps/ui/src/content/docs/installation/standalone-project.mdx b/www/apps/ui/src/content/docs/installation/standalone-project.mdx
index 5e52924c3e..0e2b513e6a 100644
--- a/www/apps/ui/src/content/docs/installation/standalone-project.mdx
+++ b/www/apps/ui/src/content/docs/installation/standalone-project.mdx
@@ -78,4 +78,14 @@ You are now ready to start building your application with Medusa UI. You can imp
import { Button, Drawer } from "@medusajs/ui"
```
-
\ No newline at end of file
+
+
+## Updating UI Packages
+
+---
+
+Medusa's design-system packages, including `@medusajs/ui`, `@medusajs/ui-preset`, and `@medusajs/ui-icons`, are versioned independently. However, they're still part of the latest Medusa release. So, you can browse the [release notes](https://github.com/medusajs/medusa/releases) to see if there are any breaking changes to these packages.
+
+To update these packages, update their version in your `package.json` file and re-install dependencies. For example:
+
+