chore: configure release-please for 6.0.0-beta line (closes #802)

[bokelley]

Summary

Configures release-please to track a 6.0.0-beta prerelease line. The Release-As: 6.0.0-beta.1 footer on the commit triggers an initial bump from 5.7.0 → 6.0.0-beta.1 when this PR merges to main; the prerelease: true + prerelease-type: "beta" config keeps subsequent feature work on the beta line (6.0.0-beta.2, beta.3, …) until GA.

Why now: most of the AdCP 3.1 SDK roadmap shipped in 5.7.0 (#350, #392, #453, #462, #749 Parts 1-3, plus ADCP_VERSION bump to 3.1.0-beta.3). The remaining work — most notably #741 canonical-formats projection — changes the public type surface (ProductFormatDeclaration discriminator), which is breaking enough to warrant a major bump.

Closes #802.

Verify before merging the release PR

This is the config-only PR — merging it doesn't cut a release. After merge, release-please opens a follow-up PR proposing v6.0.0-beta.1. Inspect that PR before merging it:

• Proposed pyproject.toml version is 6.0.0b1 (PEP 440), not the literal SemVer string 6.0.0-beta.1. The Python release-type should convert; if it doesn't, the package becomes uninstallable via pip and we need to fix the conversion before merging the release PR.
• Proposed .release-please-manifest.json is 6.0.0-beta.1 (SemVer form is fine in the manifest).
• CHANGELOG.md has a 6.0.0-beta.1 section.

Follow-up work that ships on this line

• feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741 canonical-formats v1↔v2 projection (the GA-gating piece)
• feat(testing): reference upstream-traffic recorder middleware for query_upstream_traffic adopters (adcp#3830 item 4) #347 UpstreamRecorder
• feat: permissive resolver for bare authorized_agents entries with top-level properties #711 permissive resolver for bare authorized_agents
• feat(adagents): apply revoked_publisher_domains to inline_properties branch #758 revoked_publisher_domains inline branch

Test plan

• Merge this PR
• Verify release-please opens a release PR proposing v6.0.0-beta.1
• Verify the proposed pyproject.toml version is 6.0.0b1 (NOT 6.0.0-beta.1)
• If the version format is correct, merge the release PR
• Verify PyPI receives adcp==6.0.0b1
• Verify pip install adcp==6.0.0b1 succeeds
• Verify pip install adcp still resolves to 5.7.0 (prereleases not pulled by default)

🤖 Generated with Claude Code

[aao-ipr-bot]

Held on the conversion question: whether release-please's extra-files type: "json" writer applies PEP 440 normalization to the version string it lands in pyproject.toml. The config is the right shape and the test plan's inspection gate is the right gate — but if there's a concrete one-line config change that removes the risk, better to do it now than to discover it at release-PR time.

Things I checked

• release-please-config.json:10-11 — JSON well-formed. prerelease and prerelease-type are valid release-please keys for release-type: "python". Two-line additive change, nothing else touched.
• Test plan honesty: the unchecked items in the PR body are post-merge verification steps that cannot be checked before merging the config. Fair — not a test-plan-honesty violation.
• Release-As: 6.0.0-beta.1 footer on a083f820 is single-shot. Subsequent beta increments rely on prerelease + prerelease-type + conventional-commit signals.
• PyPI: pip install adcp (no --pre) continues resolving to 5.7.0 once a 6.0.0b1 ships. Pre-release exclusion is the PEP 440 default. Safe.
• No public-API surface, no schema, no code paths.

Open question — what would flip this to approve

code-reviewer and dx-expert disagree on whether the extra-files block at release-please-config.json:12-18 actually applies PEP 440 normalization:

• code-reviewer: release-please dispatches the version write through the python strategy, so 6.0.0-beta.1 → 6.0.0b1 lands in pyproject.toml.project.version.
• dx-expert: the generic Json updater is a string writer — the python strategy's PEP 440 conversion is applied by the dedicated pyproject.toml / setup.py updaters, not by the generic json+jsonpath path. Risk: literal version = "6.0.0-beta.1" lands in pyproject, which setuptools accepts with a warning but uv / poetry / pip-tools reject.

Resolve before the release PR merges. Two ways to flip this to approve:

1. Preferred — proactive config fix. Replace the extra-files json+jsonpath block with the native pyproject updater:

   "extra-files": [{ "type": "pyproject", "path": "pyproject.toml" }]

   release-please ships this updater specifically to handle PEP 440 conversion. Removes the question entirely.
2. Or — keep this config, but verify in the release PR diff that pyproject.toml shows version = "6.0.0b1" (PEP 440), not version = "6.0.0-beta.1" (SemVer). The PR's own test plan already promises this check.

Either path is fine. Option 1 is one line; option 2 is the gate the PR body already commits to.

Minor nits (non-blocking)

1. Inert pre-major keys. release-please-config.json:7-8 — bump-minor-pre-major: true and bump-patch-for-minor-pre-major: false only fire while the current version is 0.x. At 5.7.0 they're dead config. Drop in a follow-up cleanup.
2. No auto-graduation off the beta line. Once on 6.0.0-beta.N, there is no automatic exit — going GA will require either removing prerelease / prerelease-type from this config or another Release-As: 6.0.0 footer. Worth a note in CONTRIBUTING or the release runbook so future maintainers know the exit ramp.

LGTM after either the config switches to type: "pyproject" or the release PR is verified to write 6.0.0b1 (not 6.0.0-beta.1) to pyproject.toml.

[aao-ipr-bot]

Block on a release-PR failure mode that's already in the test plan as a manual gate. The extra-files JSON updater at release-please-config.json:12-18 writes the raw SemVer string into pyproject.toml's $.project.version — for stable versions that's a no-op because SemVer and PEP 440 agree, but for 6.0.0-beta.1 it produces an invalid PEP 440 version and the wheel becomes uninstallable. Fix in this PR, not in the release PR.

Things I checked

• The two added lines (prerelease: true, prerelease-type: "beta") are valid release-please config for the Python release-type. (release-please-config.json:10-11)
• pyproject.toml's current 5.7.0 flows through extra-files cleanly because stable SemVer is already PEP 440 — no conversion needed. The prerelease branch is the first time the conversion path actually matters in this repo.
• Release-As: 6.0.0-beta.1 footer on a083f820 is correctly authored to trigger the initial bump from 5.7.0.
• .release-please-manifest.json will track the SemVer form (6.0.0-beta.1), which is fine — the bug is specifically the pyproject.toml write.

Must fix

• release-please-config.json:12-18 — extra-files writes SemVer literally. Release-please's generic Json updater (the one invoked by type: "json") applies no PEP 440 normalization; only the Python strategy's native pyproject.toml updater does. The release PR will propose version = "6.0.0-beta.1" and the PyPI publish step rejects it. Drop the extra-files entry and let release-type: python handle pyproject.toml natively, or switch the entry to a Python-aware updater. code-reviewer and dx-expert both flagged Blocker independently with the same fix.

The PR body's test-plan checkbox [ ] Verify the proposed pyproject.toml version is 6.0.0b1 (NOT 6.0.0-beta.1) is the author's own anticipation of this exact failure. Belt-and-suspenders is good, but the underlying config should produce correct output unconditionally — the manual gate is the second line of defense, not the first.

Follow-ups (non-blocking — file as issues, or fold into the same fix-up)

• README install line. pip install adcp keeps resolving to 5.7.x by PEP 440 prerelease exclusion — that's the right default, but adopters tracking beta need a one-liner near the install command pointing at pip install --pre adcp or pip install adcp==6.0.0b1.
• Migration stub. Precedent set by the existing MIGRATION_*.md files — a MIGRATION_v5_to_v6.md shell can land alongside this config flip and accrete entries as #741 (canonical-formats) lands.
• ADCP_VERSION is decoupled. The SDK going to 6.0.0-beta.1 does not flip the schema-sync skip in .github/workflows/ci.yml; ADCP_VERSION (3.1.0-beta.3) is the upstream spec version and tracks separately. Worth a sentence in the PR body so this doesn't get re-flagged later.
• feat!: during the beta line. With prerelease: true, a breaking-change commit increments to 6.0.0-beta.2 rather than rolling over. Standard behavior, but worth saying out loud somewhere — bump-minor-pre-major: true is a no-op past 1.0 and doesn't change this.

Two-line config diff, one concrete uninstallable-wheel path. Fix the updater shape, re-request review.

[bokelley]

Addressed the blocker in cd0c54f4 — dropped the extra-files entry so the Python release-type's native pyproject.toml updater handles the SemVer → PEP 440 conversion. Re-requesting review.

[bokelley]

Thanks for the quick fixup. The change in cd0c54f looks correct — dropping the extra-files JSON updater removes the path that would have written the raw SemVer string, and the Python release-type's native pyproject.toml handler will apply the 6.0.0-beta.1 → 6.0.0b1 conversion automatically. The prerelease: true + prerelease-type: "beta" addition is the right way to keep subsequent commits on the beta bump track.

The remaining verification (PEP 440 format in the release PR, manifest in SemVer form, CHANGELOG section) is still in the test-plan checklist — nothing to change there.

Ready for human review/merge when CI is green.

---

Generated by Claude Code

[aao-ipr-bot]

LGTM. Follow-ups noted below. Dropping the generic JSON extra-files writer in favor of the python release-type's native [project] version updater is the right shape — it's the only path that gets SemVer → PEP 440 normalization (6.0.0-beta.1 → 6.0.0b1) and keeps the wheel installable.

Things I checked

• release-please's python release-type owns pyproject.toml's [project] version natively and applies PEP 440 normalization — the extra-files removal at release-please-config.json:10-15 is exactly the fix cd0c54f4 claims.
• googleapis/release-please-action@v5 defaults config-file / manifest-file to repo-root paths, both of which exist. The action-level release-type: python at .github/workflows/release-please.yml:19 is harmless redundancy — the per-package config wins.
• src/adcp/__init__.py:502 reads version via importlib.metadata.version("adcp"), not a literal — so dropping extra-files does not leave __version__ stranded. No source-file patching needed.
• Release-As: 6.0.0-beta.1 footer + prerelease: true + prerelease-type: beta compose correctly: footer forces the first bump, the prerelease settings govern beta.2 → beta.3 → … until GA.
• pip resolution: pip install adcp stays on 5.7.0 post-publish (prereleases not pulled without --pre or a pre spec).
• PYPY_API_TOKEN at .github/workflows/release-please.yml:46 is the intentional repo-secret name per CLAUDE.md, not a typo.

Follow-ups (non-blocking — file as issues)

• Adopter install path is a footgun across the SemVer/PEP 440 split. pip install adcp==6.0.0-beta.1 will fail with pip's generic "no matching distribution"; the working pin is adcp==6.0.0b1 (or pip install --pre adcp). Add one line to RELEASING.md and an "Installing pre-releases" note to README.md before the beta lands — an agent generating an install command from the git tag v6.0.0-beta.1 will produce a broken pin otherwise.
• Tighten the pre-merge checklist on the release PR. Add: (1) git tag is v6.0.0-beta.1, (2) the GitHub release is marked "pre-release" (not "latest"), (3) pip install adcp with no spec still resolves to 5.7.0 after publish.
• First-publish risk is one-shot. A malformed version string burns the number permanently on prod PyPI. Worth a TestPyPI dry-run or a one-time manual-approval environment gate on the Publish to PyPI step for the 6.0.0-beta.1 release only — the prerelease config has never run end-to-end against this repo.

Clean response to the prior aao-ipr-bot flag on the extra-files PEP 440 leak — that was the load-bearing catch.

LGTM. Follow-ups noted below.