asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: add updates documentation (#11146)

Browse Source 
- Add chapter on updating Medusa
- Add section in UI docs about updating UI packages in standalone applications

Closes #10927
Closes DX-1282
This commit is contained in:
Shahed Nasser
2025-01-27 09:27:37 +02:00
committed by GitHub
parent d4cbc6218c
commit 9462f00f8d
6 changed files with 161 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
www/apps/book/app/learn/installation/page.mdx
View File

@@ -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:

110
www/apps/book/app/learn/update/page.mdx Normal file
View File

@@ -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}).`
<Note type="soon" title="Tip">
Medusa's current version is v{config.version.number}. {releaseNoteText}
</Note>
## 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.
<Note>
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.
</Note>
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.

3
www/apps/book/generated/edit-dates.mjs
View File

@@ -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"
}

37
www/apps/book/generated/sidebar.mjs
View File

@@ -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,

6
www/apps/book/sidebar.mjs
View File

@@ -553,6 +553,12 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
],
},
{
type: "link",
path: "/learn/update",
title: "Updating Medusa",
chapterTitle: "Updates",
},
{
type: "link",
path: "/learn/more-resources",

12
www/apps/ui/src/content/docs/installation/standalone-project.mdx
View File

@@ -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"
```
<Feedback title={"Install in Standalone Project"} />
<Feedback title={"Install in Standalone Project"} />
## 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:
<PackageInstall packageName="@medusajs/ui" />