Skip to content

Keep draft-spec work on a next branch, with backport and forward-port rules #1525

Open

Description

@KonstantinMirin

The SDK needs a written rule for which branch carries which spec, so that draft-spec work doesn't ship in stable releases.

Problem

main releases the 9.x line on AdCP 3.2.x: src/adcp/ADCP_VERSION is 3.2.1, and release-please cuts 9.0.0-beta.N from it. main also carries experimental AdCP 3.3 identity code written to open drafts (#1502). #1514 and #1523 add more, aligned to adcontextprotocol/adcp#7894, #8162, #8168, #8169, and #8170. Those drafts change until 3.3 is ratified, so every draft change lands in a 3.2.x release, and the 9.0 line can't go stable while part of it tracks drafts.

The repo already has most of the model. release/7.x and release/8.x carry the older majors, and release-please runs on release/8.x. What's missing is a branch for draft-spec work and a rule for moving fixes between branches.

Proposal

Use the following branches:

Branch Carries Releases
main Work against the latest ratified AdCP version (3.2.x today) The current major, through release-please
release/N.x Fixes for an older major Patch releases of that major
next Work against draft specs, such as 3.3 agent identity and Web Bot Auth Pre-releases only (for example, 10.0.0-alpha.N), from its own release-please configuration

Move changes between branches with these rules:

  • A fix lands on main first. A maintainer then backports it to each release/N.x that needs it.
  • next takes main regularly, through a merge or a forward-port PR, so it doesn't drift.
  • A change that only draft-spec work needs stays on next.
  • When a spec version is ratified, next merges into main, and the next major releases from main.
  • Labels such as backport release/8.x and forward-port next mark PRs that need a port. A backport action can open the port PRs.

Steps

  1. Create next from main, and add a release-please configuration for it.
  2. Retarget fix(identity): align AdCP 3.3 agent identity with the final spec and the Go and TS SDKs #1514 and refactor(signing): RFC 9421 on http-message-signatures; align Web Bot Auth with adcp#7894 #1523 to next.
  3. Move feat(identity): add experimental AdCP 3.3 agent identity #1502 to next before 9.0.0-beta.4 (chore(main): release 9.0.0-beta.4 #1465) ships. It isn't in a release yet.
  4. Write the rules in RELEASING.md, or in a section of CONTRIBUTING.md.

adcp-go and adcp-client have the same situation with their 3.3 identity work, tracked in adcontextprotocol/adcp#8118. If this model works here, they can adopt it too.

Activity

  1. bokelley commented on Oct 18, 2026

    @bokelley
    Contributor

    Implemented as proposed. The one difference: next is the renamed next/3.3 branch, not a fresh branch from main.

    next (done; it's not a protected branch)

    • Renamed next/3.3 → next with the branch-rename API, in two hops (next/3.3 → next-rename-tmp → next), because git can't create refs/heads/next while refs/heads/next/3.3 exists. fix(identity): align AdCP 3.3 agent identity with the final spec and the Go and TS SDKs #1514 retargeted to next automatically; refactor(signing): RFC 9421 on http-message-signatures; align Web Bot Auth with adcp#7894 #1523 stays stacked on fix(identity): align AdCP 3.3 agent identity with the final spec and the Go and TS SDKs #1514's branch.
    • 634f527: CI push and pull_request triggers now name next.
    • df3ee2c: next's own Release Please setup, in separate files so merges in either direction never change the other line's release flow:
      • .github/workflows/release-please-next.yml: runs on push to next, concurrency group release-please-next, target-branch: next, and queues release-publish.yml --ref next.
      • release-please-config.next.json: versioning: prerelease, prerelease-type: alpha, prerelease: true, changelog in CHANGELOG.next.md.
      • .release-please-manifest.next.json: baseline 9.0.0-beta.3. The adopting commit's Release-As: 10.0.0-alpha.0 footer pins the first version; after that every release bumps the alpha number (10.0.0-alpha.1, ...). I verified this with a release-please dry run before pushing.
      • The PEP 440 normalizer takes --target-branch next and accepts only release-please--branches--next--components--adcp → next.
      • release-publish.yml (its file name stays, because Trusted Publishing is bound to it) builds from main or next and waits for that branch's CI.
      • PyPI treats 10.0.0aN as a pre-release, so pip install adcp stays on 9.x.
    • 3b34786: the IPR and conventional-commit policy checks failed every PR into next ("PR must target main"). PRs into main or next now pass the base check. Push checks remain main-only.
    • Release-please has opened chore(next): release 10.0.0-alpha.0 #1533, chore(next): release 10.0.0-alpha.0, with pyproject.toml normalized to 10.0.0a0.

    PRs into main (not merged)

    Maintainer to-do, in order

    1. Merge revert: move experimental AdCP 3.3 identity from main to next #1534, then right away run the -s ours sequence on next (in revert: move experimental AdCP 3.3 identity from main to next #1534 and RELEASING.md).
    2. Merge chore(main): release 9.0.0-beta.4 #1465 after release-please regenerates it with the revert.
    3. Merge docs(releasing): write the main, release/N.x, and next branch rules #1535 (independent of the others).
    4. Add next to the release-publish environment's deployment branches. Today only main, release/7.x, and release/8.x are allowed, so a next publish would be blocked.
    5. Merge fix(identity): align AdCP 3.3 agent identity with the final spec and the Go and TS SDKs #1514, then refactor(signing): RFC 9421 on http-message-signatures; align Web Bot Auth with adcp#7894 #1523, into next before merging chore(next): release 10.0.0-alpha.0 #1533, so 10.0.0-alpha.0 ships the aligned identity code.

    adcp-go took the other route the user chose for Go: main is the AdCP 3.3 pre-release line for adcp/v3 (adcontextprotocol/adcp-go#578, which proposes adcp/v3.3.0-beta.0). Cross-SDK tracking: adcontextprotocol/adcp#8118.

  2. bokelley commented on Oct 18, 2026

    @bokelley
    Contributor

    Follow-up: #1533, the 10.0.0-alpha.0 release PR, had one failing test, the adcp.types.generated_poc alias's own v10 sunset check (REMOVED_IN_MAJOR = 10). #1536, into next, removes the alias as planned (breaking: adopters run adcp migrate v3-to-v4 --apply). All checks pass and it's approved. Merge it into next before #1533, then update #1533's branch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions