Breeze: shim fallback outside worktrees + publish-docs workflow ref

[potiuk]

Release-tooling fixes surfaced while cutting the 2026-06-02 providers release.

1. Breeze shim resolution: worktree → $AIRFLOW_REPO_ROOT → install-dir fallback (scripts/tools/setup_breeze, ADR 0017, dev/breeze/README.md).
The shim required git rev-parse to resolve a worktree, so breeze failed when invoked outside any
Airflow checkout — e.g. from the asf-dist SVN tree during
release-management clean-old-provider-artifacts --directory <asf-dist>. It now resolves the Airflow
sources in order: the current git worktree, then $AIRFLOW_REPO_ROOT (which the release docs export to
the repo root, so resolution is stable across every release process), then the dev/breeze it was
installed from (baked in at install time). Per-worktree isolation is unchanged — the fallbacks only
apply when the current directory is not an Airflow worktree, so they never override a real worktree.

2. publish-docs runs the workflow from the ref being built (workflow_commands.py).
breeze workflow-run publish-docs dispatched publish-docs-to-s3.yml from main, so building an
older release tag ran main's (newer) workflow against it and failed when the workflow had since
gained a required input/job. --workflow-branch now defaults to --ref, so the workflow version
matches the content being built; pass it explicitly to override.

3. Breeze warns when the installed shim/launcher is stale (scripts/tools/setup_breeze, path_utils.py).
The shim now carries a # breeze-shim-version: N marker that setup_breeze bumps when the shim body
changes. On startup breeze compares the installed shim's version against what the current sources would
install and warns you to re-run scripts/tools/setup_breeze if it's older (or predates versioning). The
same check also detects a leftover legacy uv tool / pipx global install and points you at migrating
to the shim.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.8)

Generated-by: Claude Code (Opus 4.8) following the guidelines

[jscheffl]

Okay'ish... but:

In provider release we set export AIRFLOW_REPO_ROOT=$(pwd -P) - why not interpreting $AIRFLOW_REPO_ROOT as fallback before inspecting other folders? Then it would be "stable" for all release processes.

[potiuk]

Okay'ish... but:

In provider release we set export AIRFLOW_REPO_ROOT=$(pwd -P) - why not interpreting $AIRFLOW_REPO_ROOT as fallback before inspecting other folders? Then it would be "stable" for all release processes.

Good idea - I think the installation fallback should be third but AIRFLOW_REPO_ROOT would be the first if set.

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 285978e v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.