airflow: Skill for Claude Code

upgrade-fab-provider

Airflow's FAB provider is tightly coupled to a specific Flask-AppBuilder release because it vendors-in and subclasses large parts of FAB's security manager. A version bump is therefore never "just change the pin" — it must be reconciled against the vendored code, and that reconciliation is enforced by a pytest alignment test, not a prek hook.

The canonical reference for a real bump is PR #66841 ("Bump flask-appbuilder to 5.2.1 and mirror new auth event hooks") — commit c72b6613fd. Read its diff first when in doubt: git show c72b6613fd.

The coupling — why this is not a one-line change

• providers/fab/pyproject.toml:75-80 explains it: Airflow vendored FAB's security-manager code into providers/fab/src/airflow/providers/fab/auth_manager/security_manager/override.py (~2700 lines) as FabAirflowSecurityManagerOverride. Every bump must review that class against upstream FAB for new / changed / removed methods.
• test_fab_alignment.py mechanically detects drift between the installed FAB package and the vendored override, and fails CI until the developer reconciles it.

Inputs

• Target version — the FAB version to move to. If not given, use the latest release on PyPI (https://pypi.org/pypi/flask-appbuilder/json → info.version). Confirm the target with the user if it is a major or minor bump (higher reconciliation risk); a patch bump can proceed.

The files a bump touches

Always:

1. providers/fab/pyproject.toml — line ~80, the flask-appbuilder==X.Y.Z pin (the only real dependency pin in the repo).
2. providers/fab/tests/unit/fab/auth_manager/security_manager/test_fab_alignment.py — EXPECTED_FAB_VERSION = "X.Y.Z" (line ~43). Must move in lockstep with the pin.
3. providers/fab/docs/index.rst — the dependency table row ``flask-appbuilder`` ``==X.Y.Z`` (line ~114).
4. providers/fab/README.rst — the Requirements table row (line ~60). Do not hand-edit — it is auto-generated. Regenerate it from the bumped pyproject.toml with the sync-provider-readme prek hook (Step 8); the hook re-renders the table whenever pyproject.toml changes. (Pre-existing bumps that predate this hook left it to release-time regeneration; today the hook is per-commit, so CI flags the drift — run it.)
5. uv.lock — regenerated (see Step 4 for the pinned-uv caveat).

Conditionally:

1. providers/fab/src/airflow/providers/fab/auth_manager/security_manager/override.py — transplant any relevant upstream FAB changes (new auth hooks, changed signatures, ported fixes). The reference bump added +37 lines here. Note: a green alignment test does not prove the transplant is unnecessary — a security fix may live inside a method Airflow vendors (see the 5.2.2 worked example below).
2. providers/fab/src/airflow/providers/fab/www/** + providers/fab/www-hash.txt — only if the new FAB ships changed static assets / templates that are re-vendored (see Step 6).
3. providers/fab/src/airflow/providers/fab/migrations/versions/** — only if the new FAB version ships DB migrations (see Step 7).

Never: no newsfragment, and do not hand-edit providers/fab/docs/changelog.rst — providers are released from main and the release manager regenerates the changelog from git log (per providers/AGENTS.md). The commit subject is the changelog entry.

Procedure

Step 1 — Determine the target version and current state

• Read the current pin: grep flask-appbuilder== providers/fab/pyproject.toml.
• Resolve the target (PyPI latest, or the user's requested version).
• Classify the jump: patch / minor / major. For minor/major, skim the FAB release notes (https://github.com/dpgaspar/Flask-AppBuilder/releases) for security-manager / model / template changes before editing.

Step 2 — Bump the three source pins