> For the complete documentation index, see [llms.txt](https://draekien-industries.wpei.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://draekien-industries.wpei.me/upgrading/upgrading.md).

# Overview

What changes between major versions, what you have to do about it, and what is on its way out.

## What version are you on now?

| You are on    | Read                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------- |
| 6.x           | [From v6.x](/upgrading/v7/from-v6.md)                                                    |
| 5.x           | [From v5.x](/upgrading/v7/from-v5.md) — the combined path, not the two pages in sequence |
| 4.x or older  | [Older upgrades](/upgrading/older.md), then come back here                               |
| 7.0.0 already | [Deprecations](/upgrading/deprecations.md) — what is going away next                     |

**If you are skipping v6, take the combined page.** The two sets of changes interact, and one v6 change had a warning that only existed in 5.5.x — so a reader coming from 5.4 or earlier gets it with no signal at all.

## The three entries in this group

* [**Upgrade to v7**](/upgrading/v7.md) — the current major. Start with [Breaking changes](/upgrading/v7/breaking-changes.md) if you want to know how bad it is before you pick a path.
* [**Deprecations**](/upgrading/deprecations.md) — API that still works today but is going away, with the version that removes it. Read this before you upgrade, not after.
* [**Older upgrades**](/upgrading/older.md) — every hop from v1 to v6, newest first.

## Every upgrade page has an agent prompt

Each of the seven upgrade pages opens with a collapsed block holding a prompt for that hop, ready to copy into Claude Code or a similar tool. It is collapsed by default, so a reader doing the upgrade by hand scrolls past one line.

Three rules apply to every one of them:

* Never suppress a diagnostic, add a pragma to disable one, or add a null-forgiving `!` to make an error go away. Every diagnostic in an upgrade has a real fix.
* Do not change behaviour to make a test pass. A test that fails after an upgrade is either a silent change you missed or a real finding.
* Do not reformat, rename, or refactor anything the upgrade does not require.

## What a prompt cannot do for you

{% hint style="warning" %}
**Step 1 of the v7 prompts needs your judgement.** The prompt asks the agent to find and report every silent change, and to decide only the ones with a mechanical answer.

Two have no mechanical answer:

* **A projection that can return null.** Whether the null meant "absent" or was never supposed to happen decides whether you convert to `Option.FromNullable` or fix the caller. Only someone who knows the domain can say.
* **Coming from 5.x, an `IsNone` branch on a value-type option.** `Option.Some(0)` now gives you a `Some`. Whether that branch was standing in for "zero" needs someone who knows what the code means. See [Silent change 3](/upgrading/older/v5-to-v6.md#silent-change-3-some-accepts-value-type-defaults).

Expect the agent to bring these to you. If it decided them on its own, that is a finding.
{% endhint %}

## If you would rather not use an agent

Every step in a prompt maps to a section on the upgrade page it sits on, and [Breaking changes](/upgrading/v7/breaking-changes.md) is the same v7 information as a reference table naming the diagnostic each break produces.