From 0ad5c920b04a146dcda9eb5bfba39f9079660e92 Mon Sep 17 00:00:00 2001
From: Brian O'Kelley <bokelley@scope3.com>
Date: Fri, 22 May 2026 16:56:19 -0400
Subject: [PATCH] docs: add MIGRATION_v5_to_v6 stub for the 6.0-beta line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors the precedent set by MIGRATION_v1_to_v2 / v3_to_v4 / v4.0_to_v4.1
— a per-major migration doc that accretes entries as breaking surfaces
land on the beta line (starting with #741 canonical-formats).

Also serves as the Release-As trigger for the initial 6.0.0-beta.1 bump,
since the original trailer on #804 was buried mid-message by the
squash-merge and release-please's parser only honors footers at the
very end of a commit message.

Refs: #802

Release-As: 6.0.0-beta.1
---
 MIGRATION_v5_to_v6.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 MIGRATION_v5_to_v6.md

diff --git a/MIGRATION_v5_to_v6.md b/MIGRATION_v5_to_v6.md
new file mode 100644
index 00000000..438f2631
--- /dev/null
+++ b/MIGRATION_v5_to_v6.md
@@ -0,0 +1,42 @@
+# Migration v5 → v6
+
+> Beta line. Surfaces here MAY change between beta increments. Track this
+> file as features land; sections will be added per-release rather than
+> upfront.
+
+## Why a major version
+
+v6 carries the type-surface changes that come with AdCP 3.1 — most
+notably the canonical-formats projection layer (#741), which alters
+the `ProductFormatDeclaration` discriminator and adds the
+`adcp.canonical_formats` public module. Adopters pinning `adcp~=5.7`
+will keep getting the v5 surface; opt into the beta with
+`pip install --pre adcp` or `pip install adcp==6.0.0b1`.
+
+## Installing the beta
+
+```bash
+pip install --pre adcp
+# or pin explicitly
+pip install adcp==6.0.0b1
+```
+
+PyPI's default resolver excludes prereleases unless `--pre` is set, so
+existing `pip install adcp` calls in production continue resolving to
+5.7.x.
+
+## What's NOT changing
+
+- `ADCP_VERSION` is the upstream protocol version (currently
+  `3.1.0-beta.3`) and is independent of the SDK package version. v6 of
+  the SDK can run against multiple `ADCP_VERSION` values; the schema
+  cache and generated types are pinned via that file, not via the
+  package version.
+- The CI schema-sync drift gate remains gated on stable upstream
+  versions (`.github/workflows/ci.yml`).
+
+## Per-release entries
+
+(Add sections here as breaking changes land. Format: heading per
+released beta increment, bullet list of breaking surfaces with
+migration recipe.)