Repository navigation
docs: add MIGRATION_v8_to_v9.md covering behavior changes not in the topic guides #1440
Description
Activity
Triage
Classification: docs
Bucket(s): docs
Status: clarifyWhat the experts said:
- docs-expert: Additive and non-breaking, format fits the established pattern — but
docs/canonical-format-kinds-migration.mdanddocs/types-9-migration.md§6 contradict each other onformat_kindtreatment; the index can't safely link both until that's resolved. - dx-expert: Strong DX benefit, most undocumented items are fine at index depth — but credential carriers (bug(auth): MCP leg accepts conflicting Authorization and alias tokens that the A2A leg rejects as ambiguous #1305) describes the failure mode without a migration path, which is dangerous for an auth-touching item.
My take: Both blocking concerns are real. The
format_kindcontradiction needs to be resolved before the index links to both guides, and a credential-carriers entry that only says "this now 401s" without telling integrators what to change is the most hazardous kind of migration note.Questions:
-
format_kindcontradiction:docs/canonical-format-kinds-migration.mddescribesformat_kindas a closedCanonicalFormatKindenum in 9.0 (unknown kinds rejected,iscomparisons work), whiledocs/types-9-migration.md§6 says 9.0 makesformat_kinda barestreverywhere (unknown kinds retained,iscomparisons break). Which guide is correct, or do they describe different subpopulations of fields? The index needs to link one or both accurately, and at least one may need updating before this ships. -
Credential carriers migration path (bug(auth): MCP leg accepts conflicting Authorization and alias tokens that the A2A leg rejects as ambiguous #1305): The issue body explains what 9.0 rejects (mixed carriers, empty
x-adcp-authalongside a valid Bearer, disagreeing tokens), but not what an integrator should actually do. For a seller that was sending bothAuthorization: Bearerandx-adcp-authin 8.x: what's the correct 9.0 migration? Remove the legacy header? Configure a single authoritative carrier? A separatedocs/credential-carriers-migration.mdtopic guide (following the pattern of the other v9 guides) would cover this adequately; otherwise the index entry should include the fix, not just the failure mode.
Triaged by Claude Code. Session: https://claude.ai/code/session_012XVoBQ5iPGeDiQEYG8cSTR
Generated by Claude Code
- docs-expert: Additive and non-breaking, format fits the established pattern — but
Summary
9.0's breaking changes are documented across topic guides (
docs/types-9-migration.md,docs/reporting-caller-ownership-migration.md,docs/canonical-format-kinds-migration.md,docs/request-signing-migration.md). There is no top-levelMIGRATION_v8_to_v9.md, which every earlier major has had (up toMIGRATION_v7_to_v8.md). Some changes that broke or nearly broke a production seller aren't in any of the guides.Behavior changes we'd like called out in one place
Authorization: Bearerand fell back to a legacy alias such asx-adcp-authotherwise. 9.0 inspects every carrier and answers 401 when any is empty or malformed, or when tokens differ. Requests that authenticated on 8.x now fail: aBasicor bare-tokenAuthorizationnext to a validx-adcp-auth, an emptyx-adcp-authnext to a valid Bearer, and repeated headers with different tokens. (We shipped a log-only audit to measure this before upgrading.)format: uri/hostnamechecks on inbound requests. Lax payloads that 8.x coerced now returnValidationError.FrequencyCap()with no field group, orCreateMediaBuyRequestwithout packages or a proposal.Ask
Add
MIGRATION_v8_to_v9.mdas the index: one line per breaking change, linking to the topic guides, plus the items above that no guide covers yet.