Migration Guide: [Product name] [old version] to [new version]

Guide for users who must move from one major version, API or platform to another: who is affected, what breaks, when, and the exact steps to migrate, verify and roll back. Based on common industry practice for upgrade and migration documentation. Replace every [bracketed] value and every row marked Example.

1. Who must migrate

You must migrate if any of these apply:

• You run [Product name] [2.x] self-hosted, or
• You call the API with the header Example-Version: 2024-*, or
• You use the [Python SDK below 5.0 / JavaScript SDK below 6.0].

You are not affected if you use only the hosted web app; it was upgraded automatically on YYYY-MM-DD. To check your version, run [product] --version or look at Settings > About.

2. Why this change

Version [3.0] replaces [the legacy XML import pipeline] with [a streaming JSON pipeline], which [cuts import time by about 60% on files over 100 MB] and removes [the dependency on an unsupported library with known vulnerabilities]. Several older options were removed to make configuration consistent.

3. Timeline

4. Breaking changes

4.1 Deprecated but still working

5. Pre-migration checklist

6. Migration steps

6.1 Upgrade the package

pip install "example-sdk>=5.0,<6"
[product] --version

Expected output: 3.0.x.

6.2 Run the automated migration tool

The tool rewrites configuration and reports what it could not change.

[product] migrate --from 2 --to 3 --dry-run
[product] migrate --from 2 --to 3

Review migration-report.md; every line marked MANUAL needs a step below.

6.3 Convert configuration

Before:

import:
  format: xml
  batch: 500

After:

import:
  format: json
  batch_size: 500

6.4 Update code

Before (2.x):

page = 1
while True:
    items = client.get_items(page=page)
    if not items:
        break
    for item in items:
        total += float(item["amount"])
    page += 1

After (3.0):

for item in client.items.list().auto_paging_iter():
    total += item.amount / 100  # amount is now in minor units

7. Data migration

On first start, [3.0] converts stored records to the new schema. Time needed is roughly linear in the number of records: $t \approx N / 50\,000$ minutes, so about 20 minutes for one million records. The service is read-only during conversion.

8. Verification

9. Rollback

Roll back if verification fails or error rates rise above [2%] within [one hour]. Steps:

1. Put the service in maintenance mode.
2. Reinstall [2.x]: pip install "example-sdk<5".
3. Restore the backup from the pre-migration checklist.
4. Restore the old configuration from version control.

Data written after the migration started is lost on rollback; export it first with [product] export --since "YYYY-MM-DD HH:MM" if needed.

10. FAQ

Can I skip from 1.x straight to 3.0? No. Migrate to [2.9] first, then follow this guide.

Can 2.x and 3.0 run side by side? Yes, against separate databases. They cannot share one database after conversion.

Will my API keys keep working? Yes. Only the Example-Version header and the response formats change.

What if I miss the deadline? Your integration keeps working until end of life, but without security fixes. After end of life, API calls fail.

11. Getting help

Ask in [the migration discussion forum] or contact [[email protected]] with your migration-report.md, current version and the failing step.

Standard and licence note

Based on common industry practice for upgrade and migration guides (impact first, breaking-change table, timeline, steps, verification and rollback). Template licence: MIT.