# 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*.

<!--
Guidance: How to use this template
- Lead with impact. Readers first need to know whether they are affected
  and by when; only then will they read the steps.
- List every breaking change, even small ones. One missing row costs more
  support time than the whole guide took to write.
- Show before and after code for each change that needs a code edit.
- Test the migration steps on a real project and include a rollback path.
-->

| Field | Value |
|---|---|
| From version | [2.x] |
| To version | [3.0] |
| Migration deadline | YYYY-MM-DD |
| Owner | [@release-manager] |
| Status | [Draft / Published] |
| Last updated | YYYY-MM-DD |

## 1. Who must migrate

<!-- Guidance: Give readers a quick way to tell whether they are affected. A checklist or a command that reports their version works best. -->

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

<!-- Guidance: One short paragraph on the benefits. Readers accept work more readily when they know what they gain. Keep marketing out. -->

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

<!-- Guidance: Give every date that matters and what happens on it. Use absolute dates, not "in three months". -->

| Date | Milestone | What happens |
|---|---|---|
| YYYY-MM-DD | [3.0] released | New version available; [2.x] still fully supported |
| YYYY-MM-DD | [2.x] deprecated | Security fixes only; warnings in logs and API responses |
| YYYY-MM-DD | Migration deadline | Last day [2.x] receives security fixes |
| YYYY-MM-DD | [2.x] end of life | API version rejected with `410 Gone`; no support |

```mermaid
gantt
    title Migration timeline
    dateFormat YYYY-MM-DD
    section Versions
    3.0 available          :a1, 2026-11-01, 365d
    2.x security fixes only :a2, 2026-11-01, 180d
    2.x end of life        :milestone, 2027-05-01, 0d
```

## 4. Breaking changes

<!-- Guidance: One row per change. Impact says what fails if the reader does nothing; Action says what to do. Link each row to its step in section 6. -->

| ID | Area | Old (2.x) | New (3.0) | Impact if not changed | Action |
|---|---|---|---|---|---|
| BC-01 | Configuration | `import.format: xml` | `import.format: json` | Startup error | Convert files (6.3) |
| BC-02 | API | `GET /items?page=2` | `GET /items?starting_after=<id>` | `400 Bad Request` | Use cursor pagination (6.4) |
| BC-03 | API | `amount` as string `"12.50"` | `amount` as integer `1250` (minor units) | Wrong amounts if parsed as decimal | Multiply by 100 (6.4) |
| BC-04 | SDK | `client.get_items()` | `client.items.list()` | `AttributeError` | Rename calls (6.4) |
| BC-05 | Runtime | Python 3.8 supported | Python 3.10 minimum | Install fails | Upgrade Python (5) |
| [BC-nn] | [Area] | [Old] | [New] | [Impact] | [Action] |

### 4.1 Deprecated but still working

| Feature | Replacement | Removal planned |
|---|---|---|
| `--legacy-auth` flag | OAuth device flow | [4.0] |
| `item.created` timestamp in seconds | `item.created_at` ISO 8601 | [4.0] |

## 5. Pre-migration checklist

<!-- Guidance: Everything to have in place before step 1. Include a backup and a test environment. -->

| # | Item | Done |
|---|---|---|
| 1 | Read every breaking change in section 4 and mark the ones that apply | [ ] |
| 2 | Take a full backup and confirm it restores | [ ] |
| 3 | Upgrade runtime to [Python 3.10+ / Node.js 20+] | [ ] |
| 4 | Prepare a staging environment with a copy of production data | [ ] |
| 5 | Search your code for old calls: `grep -rn -e get_items -e "page=" src/` | [ ] |
| 6 | Schedule a maintenance window of about [1 hour] | [ ] |
| 7 | Tell users and dependent teams the date and expected impact | [ ] |

## 6. Migration steps

<!-- Guidance: Numbered steps in the order they must run, each with a verification. Do staging first, then production. -->

### 6.1 Upgrade the package

```bash
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.

```bash
[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:

```yaml
import:
  format: xml
  batch: 500
```

After:

```yaml
import:
  format: json
  batch_size: 500
```

### 6.4 Update code

Before (2.x):

```python
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):

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

## 7. Data migration

<!-- Guidance: Describe any change to stored data: what is transformed, how long it takes, whether it is reversible, and how to check it. -->

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.

| Data | Change | Reversible |
|---|---|---|
| Items | `amount` decimal converted to integer minor units | Yes, by restoring backup |
| Import history | XML payloads archived to `archive/` | Yes |
| Sessions | Cleared; users sign in again | Not needed |

## 8. Verification

<!-- Guidance: Give checks with clear pass conditions so readers know the migration is complete. -->

| Check | How | Pass condition |
|---|---|---|
| Version | `[product] --version` | `3.0.x` |
| Record count | Compare `SELECT count(*) FROM items` before and after | Equal |
| Totals | Compare sum of amounts before and after (× 100) | Equal |
| API | Call `GET /items?limit=1` with new headers | `200 OK` |
| Logs | Search for `DEPRECATED` | No matches from your code |

## 9. Rollback

<!-- Guidance: Say when to roll back, how, and what is lost. Without this section, teams hesitate to start. -->

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

<!-- Guidance: Answer the questions support received during beta. Short answers with links. -->

**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

<!-- Guidance: Say where to ask and what to include. -->

Ask in [the migration discussion forum] or contact [support@example.com]
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.