(airflow) branch v3-3-test updated: [v3-3-test] Explain how to rebuild provider packages with the release manager's flit (#73699) (#73705)

[sh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

shahar1 pushed a commit to branch v3-3-test
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/v3-3-test by this push:
     new 6b858a8dfe5 [v3-3-test] Explain how to rebuild provider packages with the release manager's flit (#73699) (#73705)
6b858a8dfe5 is described below

commit 6b858a8dfe57f0fe87921f03aa93b2d2f25e7728
Author: github-actions[bot] <41...@users.noreply.github.com>
AuthorDate: Fri Sep 25 10:10:23 2026 +0300

    [v3-3-test] Explain how to rebuild provider packages with the release manager's flit (#73699) (#73705)
    
    The 2026-09-22 providers wave was built with flit 4.0.2 while the tag's
    dev/breeze/uv.lock locks flit 4.1.0. Because flit builds without isolation,
    voters following the reproducibility check got 75 wheels differing only in
    the WHEEL Generator line, with no documented way to reproduce the release
    manager's environment.
    (cherry picked from commit 70bc47c859dccd20129b1c6c15a9a4e732c1177c)
    
    
    Generated-by: Claude Opus 5
    
    Co-authored-by: Jarek Potiuk <ja...@potiuk.com>
---
 dev/README_RELEASE_PROVIDERS.md | 48 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md
index eedaa88cbd8..ce3134b532f 100644
--- a/dev/README_RELEASE_PROVIDERS.md
+++ b/dev/README_RELEASE_PROVIDERS.md
@@ -677,6 +677,15 @@ breeze release-management prepare-tarball --tarball-type apache_airflow_provider
 The `prepare-*-distributions` commands should produce the reproducible `.whl`, `.tar.gz` packages in the dist folder.
 The `prepare-tarball` command should produce reproducible `-source.tar.gz` tarball of sources.
 
+**Build with the locked Breeze.** Run these with the `breeze` shim installed by
+`scripts/tools/setup_breeze`, from a plain `git clone` (not a `git worktree`). The shim runs Breeze
+with the dependencies locked in the checked-out `dev/breeze/uv.lock`, and that lock is what decides
+the flit version: `flit build` runs without build isolation, so the installed flit - not the
+`flit_core==` pin in the providers' `pyproject.toml` - builds every package and stamps its version
+into the `Generator:` line of each wheel's `WHEEL` file. A `breeze` installed separately (for example
+an older `uv tool install` of `dev/breeze`) can carry a different flit, and voters rebuilding from the
+tag with the locked version then get wheels that differ in that line.
+
 > [!IMPORTANT]
 > `--version-suffix ""` is passed deliberately, and the empty value is the point: the packages
 > committed to SVN carry the **final** version in their filename (`...-6.0.1-py3-none-any.whl`), with
@@ -1235,7 +1244,9 @@ it means that the build has a verified provenance.
 
 How to verify it:
 
-1) Change directory to where your airflow sources are checked out:
+1) Change directory to where your airflow sources are checked out. It must be a plain `git clone`,
+not a `git worktree`: Breeze refuses to build provider sdists from a worktree, because flit does not
+recognise one and would silently produce incomplete sdists.
 
 ```shell
 cd "$AIRFLOW_REPO_ROOT"
@@ -1254,20 +1265,49 @@ git checkout providers/${RELEASE_DATE}
 rm -rf dist/*
 ```
 
-4) Build the packages using checked out sources
+4) Check which flit version the release manager built the wheels with, and which one Breeze locks at
+the tag. `flit build` runs without build isolation, so the flit installed in Breeze's environment -
+not the `flit_core==` pin in the providers' `pyproject.toml` - builds the packages, and it writes its
+version into the `Generator:` line of every wheel's `WHEEL` file. A different flit version produces
+wheels that differ only in that line (and in its hash in `RECORD`).
+
+```shell
+for i in ${PATH_TO_AIRFLOW_SVN}/providers/${RELEASE_DATE}/*.whl
+do
+  unzip -p "$i" '*.dist-info/WHEEL' | grep Generator
+done | sort | uniq -c
+grep -A1 '^name = "flit"$' dev/breeze/uv.lock
+```
+
+5) Build the packages using checked out sources.
+
+If the `Generator:` version matches the `flit` version in `dev/breeze/uv.lock`, build with the
+`breeze` shim installed by `scripts/tools/setup_breeze` - it runs Breeze with the dependencies locked
+at the checked-out tag:
 
 ```shell
 breeze release-management prepare-provider-distributions --include-removed-providers --distribution-format both --version-suffix ""
 breeze release-management prepare-tarball --tarball-type apache_airflow_providers --version "${RELEASE_DATE}"
 ```
 
-5) Switch to the folder where you checked out the SVN dev files
+If they differ, build with a Breeze environment pinned to the release manager's flit version.
+`uv run --with flit==...` does not override the locked version, so use a separate virtualenv:
+
+```shell
+export FLIT_VERSION=4.0.2  # the version from the Generator: line
+uv venv /tmp/breeze-flit
+uv pip install --python /tmp/breeze-flit/bin/python -e ./dev/breeze "flit==${FLIT_VERSION}" "flit-core==${FLIT_VERSION}"
+/tmp/breeze-flit/bin/breeze release-management prepare-provider-distributions --include-removed-providers --distribution-format both --version-suffix ""
+/tmp/breeze-flit/bin/breeze release-management prepare-tarball --tarball-type apache_airflow_providers --version "${RELEASE_DATE}"
+```
+
+6) Switch to the folder where you checked out the SVN dev files
 
 ```shell
 cd ${PATH_TO_AIRFLOW_SVN}/providers/${RELEASE_DATE}
 ```
 
-6) Compare the packages in SVN to the ones you just built
+7) Compare the packages in SVN to the ones you just built
 
 ```shell
 for i in *.tar.gz *.whl