docs(migration)!: add v4.0 → v4.1 migration guide#302
Merged
Conversation
Document the three breaking changes folded into the 4.1 release so
upgraders have a single artifact to consult:
1. ``ADCPClient.pending_task_id`` → ``ADCPClient.active_task_id``
(and the same on ``A2AAdapter``); ``context_id=`` / ``reset_context()``
raise ``TypeError`` instead of ``ValueError`` on non-A2A protocols.
2. ``FormatId.__name__`` is now ``"FormatReferenceStructuredObject"``
because AdCP 3.0.1 polished ``core/format-id.json``'s title.
Public ``FormatId`` keeps working via the aliases module; pickled
instances and reflection on ``__name__`` break.
3. ``MEDIA_BUY_STATE_MACHINE`` no longer has ``pending_activation`` —
replaced with the spec-correct ``pending_creatives`` and
``pending_start``.
BREAKING CHANGE: ``FormatId.__name__`` and ``__qualname__`` change
from ``"FormatId"`` to ``"FormatReferenceStructuredObject"`` because
AdCP 3.0.1 polished the schema title on ``core/format-id.json``. The
public ``adcp.FormatId`` alias keeps working — ``Format(format_id=
FormatId(...))`` and ``isinstance(x, FormatId)`` are unchanged. Two
niche cases break: pickled ``FormatId`` instances from 4.0 fail to
unpickle on 4.1, and snapshot tests / log scrapers asserting on
``__name__`` see the rename. See MIGRATION_v4.0_to_v4.1.md.
BREAKING CHANGE: ``MEDIA_BUY_STATE_MACHINE`` no longer accepts
``"pending_activation"`` as a key — that string is not part of the
AdCP v3 ``enums/media-buy-status.json``. ``valid_actions_for_status
("pending_activation")`` now returns ``[]``. Use ``"pending_creatives"``
(creatives still awaiting approval) or ``"pending_start"`` (creatives
approved, awaiting flight start) per the spec. See
MIGRATION_v4.0_to_v4.1.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add `MIGRATION_v4.0_to_v4.1.md` documenting the three breaking changes folded into 4.1 (the `pending_task_id` rename, the `FormatId.name` change from AdCP 3.0.1's schema title polish, and the `MEDIA_BUY_STATE_MACHINE` key rename from `pending_activation` → `pending_creatives` + `pending_start`).
Why
The first one is already in release-please's BREAKING section because it shipped under `feat(a2a)!:`. The other two arrived under `chore(types):` (#292) and `fix(handlers):` (#289), which release-please grades as Miscellaneous Chores / Bug Fixes — not loud enough for breaking-pickle and behavior-change-on-stored-status-strings. This commit's `docs(migration)!:` type plus the two `BREAKING CHANGE:` footers brings them into the BREAKING CHANGES section of the auto-generated 4.1.0 release notes.
What was tested
Out of scope
🤖 Generated with Claude Code