A2ui Release Python

Releasing the A2UI Python SDKs

This skill turns a one-line request such as "release a2ui-core patch" or "release the Python SDKs" into the full release sequence.

Publishing is done by the Release Python SDKs workflow. This skill does not reimplement any of it. Its job is the part the workflow cannot do for itself: choosing the bump, catching the problems that a workflow run would discover too late, and following through afterwards.

Background for anything not covered here: docs/contributing/release.md.

[!CAUTION] Publishing to PyPI is irreversible. A version can be yanked but never reused or deleted. Step 4 is a mandatory stop. Never dispatch a run with dry_run: false without an explicit go-ahead from the maintainer in the current conversation.

What runs where

The workflow performs the release. Nothing here does. Building, tagging, pushing tags, staging in the Artifact Registry and triggering the Exit Gate all happen inside release-pypi.yml, and only there. It could not be otherwise: the Exit Gate authenticates by matching the OIDC claim …/release-pypi.yml@refs/heads/main, so a local upload has no credentials to use.

The local calls are limited to the read-only subcommands notes, next, current, tag, plan and check. They exist to answer two questions before spending a CI run: is there anything to release, and will preflight reject it.

[!IMPORTANT] A local plan is a prediction, not the release. It is computed from the tags in the local checkout, so it is only as current as the last fetch — which is why Step 1 fetches first. The plan the workflow computes is the one that counts, and Step 3 reads it back out of the run before anyone approves it.

Never run cut-changelog --write, git tag, git push, uv build or twine by hand to perform a release. If the workflow cannot do it, fix the workflow.

[!IMPORTANT] One exception, and it is deliberate: the changelog pull request has to be opened by a person, not by the workflow. GitHub does not start workflow runs for events caused by GITHUB_TOKEN, so a pull request the workflow opened would never get the required checks and could never be merged. The workflow pushes the branch; Step 6 opens the pull request.

Step 1: Work out what is being released

Two things are needed: PACKAGE (a2ui-core, a2ui-agent-sdk, or both) and BUMP (patch, minor, or major). Derive both from the changelogs. Never infer them from the phrasing of the request.

Fetch first. Versions are derived from tags, so every number below is wrong if the checkout is behind:

git fetch origin main --tags

python3 .github/scripts/release_version.py notes --package a2ui-core
python3 .github/scripts/release_version.py notes --package a2ui-agent-sdk

Choose the packages. Release only those with a non-empty ## Unreleased. Empty output means that package has nothing to release, whatever was asked for. A plural request such as "release the Python SDKs" does not mean both — if only one has pending entries, that one is the release. If neither does, stop and say so.

Check the exit status, not just the output. The two failure shapes are different answers:

[!NOTE] Dispatching both when one side is empty is not dangerous, just wasteful. The plan builds, then preflight rejects the empty package and the run fails several minutes in. The check above costs a second.

Choose the bump. Read the entries: fixes only means patch, new features mean minor, a breaking change means major. Preview the result with plan, which returns exactly what the workflow will compute — version, tag and release notes for every selected package:

python3 .github/scripts/release_version.py plan --package "${PACKAGE}" --bump "${BUMP}"

[!IMPORTANT] both applies one bump level to both packages. The workflow takes a single bump input, so build_plan raises both versions by the same amount. When the two warrant different levels — say fixes in a2ui-core and a feature in a2ui-agent-sdk — there is no single right answer. Put the choice to the maintainer:

• Take the higher level for both. One release, one changelog pull request. The cost is an over-bumped version on the quieter package.
• Run two single-package releases. Correct versioning, but the changelog pull request from the first must be merged before starting the second, or the Step 2 guard will block it. Release a2ui-core first if both are going out, since a2ui-agent-sdk depends on it.

Put the proposal to the maintainer with ask_question, showing the pending entries and the resulting versions, and let them correct it.

Step 2: Preflight locally

These checks cost seconds and catch the failures that are expensive to hit mid-run. Run all of them before dispatching anything.

1. No outstanding changelog branch from a previous release. This is the one the workflow cannot detect. Until the last release's changelog lands, the entries are still under ## Unreleased, and this release would repeat them in its notes.

git ls-remote --heads origin 'release/changelog-*'

Check the branch, not the pull request: the release stops at the branch, so there may be no pull request yet. The repository deletes branches on merge, so empty output means the last changelog landed.

Any output means stop. Get that change merged first — open the pull request if nobody has — then start over from Step 1, because the pending entries will have changed.

2. The checkout is clean and matches the remote. Step 1 already fetched. The concern here is local edits: the workflow reads the changelogs and tags from main, so an uncommitted changelog change makes the local preview describe a release that is not the one that will go out.

git status --short --branch

Uncommitted changes under python/*/CHANGELOG.md, or a branch behind origin/main, mean stop and say what was found.

3. The repository's own preflight passes. Use the version from Step 1. This is the same check the workflow runs, so a failure here is a failure there:

python3 .github/scripts/release_version.py check --package "${PACKAGE}" --version "${VERSION}"

It rejects an empty ## Unreleased, a version that already has a tag, and an a2ui-core version outside the range that a2ui-agent-sdk pins.

[!IMPORTANT] That last one is the usual surprise. An a2ui-core minor or major bump needs the a2ui-core>=... pin in a2ui_agent/pyproject.toml widened in the same release. That is a code change requiring its own reviewed pull request, so it has to land before the release, not during it. If the check reports this, stop and tell the maintainer what needs widening.

Step 3: Dry run

A dry run builds and stages the artifacts in the Exit Gate Artifact Registry, removes them again, and pushes nothing.

gh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \
  -f package="${PACKAGE}" -f bump="${BUMP}" -f dry_run=true

Wait a few seconds, then find the run and watch it:

gh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \
  --json databaseId,status,url
gh run watch "${RUN_ID}" --repo a2ui-project/a2ui --exit-status

[!TIP] Use the full databaseId. A truncated run ID returns 404.

If it fails, read the failing step's log and consult Troubleshooting below before retrying.

When it passes, read back the plan the run actually computed. The dry run does not upload the plan artifact, and step summaries are not available over the API, but the plan step prints the JSON into the log:

gh run view "${RUN_ID}" --repo a2ui-project/a2ui --log \
  | grep -A 20 'Build the release plan'

Compare it against the local plan output from Step 1. They are computed the same way and should agree. If they differ, a tag landed in between — stop and work out why before going any further.