Migration Guide Template

Migrations lower blood pressure. They explain what’s changing, why it matters, and how to get through the upgrade with verifications and rollbacks close at hand.

❌ DO NOT COPY — Guidance & Constraints

Keep the frontmatter complete (title, description, icon, versionFrom, versionTo, and optional releaseDate). Readers should know at a glance what versions they are moving between.
Start with context: summary table + “Should you upgrade?” checklist. Highlight deadlines with <Warning> and call out optional paths with <Tip>.
Break the body into Plan → Migrate → Validate. Use numbered headings inside Migrate and put rollback instructions directly after any risky step.
When porting older migration guides, keep existing change tables, screenshots, and warnings—slot them into this format unless the upgrade path has materially changed.
Document breaking changes with an Old behavior vs New behavior table. Use <Info icon="check"> for mandatory verification steps.
Optional flow diagrams are allowed, but only when a left-to-right Mermaid (graph LR) clarifies the upgrade path.
End with two CTA cards (left = deep dive reference, right = applied example) and keep the comment reminder for reviewers.

✅ COPY THIS — Content Skeleton

Paste the block below, swap placeholders, and delete optional sections only after you’ve confirmed they aren’t needed.

mdx

---
title: [Migration title]
description: [Why this upgrade matters]
icon: "arrows-rotate"
versionFrom: "[current version]"
versionTo: "[target version]"
releaseDate: "[YYYY-MM-DD]" # Optional
---

# [Migration headline — state the move]

| Scope | Effort | Downtime |
| --- | --- | --- |
| [Platform/OSS/etc.] | [Low/Medium/High] ([~time]) | [Expected downtime impact] |

<Info>
  **Should you upgrade?**
  - [Criteria 1]
  - [Criteria 2]
  - [Criteria 3]
</Info>

<Warning>
  [Breaking deadline or critical change. Remove if not needed.]
</Warning>

## Timeline

- [Date]: [Milestone]
- [Date]: [Milestone]
```mermaid
graph LR
  A[Plan] */} B[Migrate]
  B */} C[Validate]
  C */} D[Roll back if needed]

Plan

[Actionable preparatory step]
[Stakeholder alignment or backup note]

Migrate

1. [Upgrade dependencies]

bash

pip install mem0ai==[version]
npm install mem0ai@[version]

<Tip> [Optional hint or staging strategy.] </Tip> <Info icon="check"> Run `[verification command]` and confirm it reports `[expected output]`. </Info>

2. [Update configuration]

diff

- memory_filters = true
+ filters = true

<Warning> **Breaking change:** `[Explain the new behavior and what to update]`. </Warning>

Rollback: [Describe how to revert this specific step].

3. [Run data migrations or API updates]

python

[Code snippet showing new behavior]

<Info icon="check"> `[Describe logs, metrics, or sample response that proves success]`. </Info>

Validate

[Smoke test or script] returns expected result.
[Dashboard or metric] shows [desired signal].
[End-to-end scenario] passes with [new behavior].

Breaking changes

Old behavior	New behavior	Action
`[Explain]`	`[Explain]`	`[What to change]`
`[Explain]`	`[Explain]`	`[What to change]`

Rollback plan

[Step-by-step rollback instructions]
[Restore backups or redeploy previous image]
[Validation after rollback]

Known issues

[Issue name] — [Status]. [Workaround or link].
[Issue name] — [Status]. [Workaround or link].

After you migrate

[Link to feature guide showing new capabilities]
[Link to cookbook or integration that benefits from the upgrade]

<CardGroup cols={2}> <Card title="[Deep dive reference]" description="[Why this reference matters post-migration]" icon="book" href="#reference-link" /> <Card title="[Applied example or next step]" description="[What readers can build now]" icon="rocket" href="#example-link" /> </CardGroup> ```

✅ Publish Checklist

Versions (versionFrom, versionTo) and timelines are accurate.
Every breaking change is highlighted via table or <Warning>.
Rollback instructions are present and placed immediately after risky steps.
Verification steps use <Info icon="check"> and are actionable.
Optional sections (Mermaid, tips) removed if unused.
Final <CardGroup> contains exactly two cards with valid links.

Browse Other Templates