From d56a89f03555175d92f70cf4093de6ff6e4d10d1 Mon Sep 17 00:00:00 2001 From: Shahar Epstein <60007259+shahar1@users.noreply.github.com> Date: Fri, 19 Jun 2026 09:05:27 +0300 Subject: [PATCH 1/2] Add update-providers-next-version step to provider docs skill The prepare-providers-documentation skill stopped after regenerating the build templates and handed back to the regular release workflow, leaving 'breeze release-management update-providers-next-version' implicit. That step resolves inter-provider dependencies pinned with '# use next version' to the just-released versions and must run before the PR is opened; missing it ships the wave with stale lower bounds and needs a follow-up PR to fix. Make the skill run it as an explicit phase and check for it during validation. --- .../prepare-providers-documentation/SKILL.md | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md b/.agents/skills/prepare-providers-documentation/SKILL.md index fb5602f894a62..d3c90f546a779 100644 --- a/.agents/skills/prepare-providers-documentation/SKILL.md +++ b/.agents/skills/prepare-providers-documentation/SKILL.md @@ -487,6 +487,30 @@ new versions you just wrote. It will not touch `changelog.rst`. > `airflow-providers-commits` directive). It will be regenerated on the > next full release. No action needed here. +#### 4d. Resolve `# use next version` inter-provider pins + +Contributors can defer an inter-provider dependency bump by pinning it in +`pyproject.toml` with a trailing `# use next version` comment, instead of +hard-coding a version that does not exist yet. Now that the versions are +bumped, resolve those pins: + +```bash +breeze release-management update-providers-next-version +``` + +This rewrites every `# use next version` dependency to the just-bumped +version of the referenced provider and removes the comment. + +> [!IMPORTANT] +> **Run this every time, before opening the PR — even when you believe no +> provider uses the comment** (the command is a safe no-op when none do). +> Skipping it ships the wave with stale lower bounds on inter-provider +> dependencies; once the PR is merged the only remedy is a separate +> follow-up PR. This is the "Update versions of dependent providers to the +> next version" step in `dev/README_RELEASE_PROVIDERS.md` — it lives between +> doc preparation and PR creation, so it is easy to forget when the skill +> hands back to the regular release workflow. + ### Phase 5 — Validate Run the same checks the release manager would run: @@ -506,11 +530,14 @@ provider-by-provider: - Confirm the version in `provider.yaml` matches the bump rule. - Confirm `changelog.rst` has the right sections populated. +- Confirm Phase 4d ran: no `# use next version` comment remains where the + referenced provider was bumped in this wave. - Flag anything where Phase 3.5 had to escalate, so the RM can double-check. Stop here. Do not commit, do not push — the release manager opens the PR themselves following the regular release workflow in -`dev/README_RELEASE_PROVIDERS.md`. +`dev/README_RELEASE_PROVIDERS.md`. Make sure Phase 4d +(`update-providers-next-version`) has been run before that PR is opened. --- @@ -652,6 +679,11 @@ no leftover "Please review …" markers from a prior interactive incremental flow before invoking this skill), remove them as part of the final pass. Then walk the diff with the release manager. +If the incremental run bumped a provider to a *new* version (Incremental +Phase 3.5), re-run Phase 4d (`update-providers-next-version`) as well — a +`# use next version` pin on that provider must resolve to the freshly +bumped version before the rebased PR is pushed. + --- ## Cross-Cutting Rules From c2631206b2830d498cbbeeefab8ad773ccbcf937 Mon Sep 17 00:00:00 2001 From: Shahar Epstein <60007259+shahar1@users.noreply.github.com> Date: Fri, 19 Jun 2026 09:09:14 +0300 Subject: [PATCH 2/2] Document the next-version step in the provider release guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflect in README_RELEASE_PROVIDERS.md that the prepare-providers-documentation skill now runs update-providers-next-version itself, and that an incremental update which bumps a version must re-run that step on the rebased branch — for both the skill and the interactive breeze flows. --- dev/README_RELEASE_PROVIDERS.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md index 36841800f72e9..d958fc68a0857 100644 --- a/dev/README_RELEASE_PROVIDERS.md +++ b/dev/README_RELEASE_PROVIDERS.md @@ -282,6 +282,10 @@ uncertain or major-bump cases with you, and application via direct edits to `pro (`breeze release-management prepare-provider-documentation --reapply-templates-only`) so the skill stays consistent with the existing tooling. +The skill also runs the [Update versions of dependent providers to the next +version](#update-versions-of-dependent-providers-to-the-next-version) step for you, so you do not +need to run that command separately when using the skill. + If you set ``DISTRIBUTIONS_LIST``, the skill scopes itself to that subset automatically. The skill (and the underlying breeze tooling) determines the new version of provider as follows: @@ -323,6 +327,12 @@ removed. breeze release-management update-providers-next-version ``` +> [!NOTE] +> The `prepare-providers-documentation` skill runs this command automatically as part of its +> flow, so you only need to run it by hand when you prepared the documentation with the +> interactive breeze command instead of the skill. Run it regardless of whether you think any +> provider uses the `# use next version` comment — the command is a no-op when none do. + ## Create a PR with the changes Make sure to set labels: `allow provider dependency bump` and `skip common compat check` to the PR, @@ -346,6 +356,13 @@ This usually takes some time, so before merging you need to rebase it to latest are no new, incremental updates (one or two merged commits in the meantime). If there are - you still have a chance to incorporate them via the **incremental update** flow. +> [!IMPORTANT] +> Whenever an incremental update bumps a provider's version, the [Update versions of dependent +> providers to the next version](#update-versions-of-dependent-providers-to-the-next-version) step +> must be applied **again** on the rebased branch — regardless of whether you prepared the docs with +> the skill or the interactive breeze command. The skill re-runs it automatically; with the +> interactive `--incremental-update` flow you must run the command yourself. + The recommended way is to invoke the same `prepare-providers-documentation` skill — it has a dedicated **Incremental Update** section that detects which commits on the rebased branch are not yet referenced in the existing `changelog.rst`, classifies only those new commits with the same per-PR sub-agent @@ -365,6 +382,9 @@ recognizes the incremental scenario and walks through: 4. Confirming any version-bump escalation with you explicitly before applying. 5. Inserting the new entries under the correct sections of the existing latest-version block. 6. Validating that no leftover `Please review` markers remain. +7. Re-running [Update versions of dependent providers to the next + version](#update-versions-of-dependent-providers-to-the-next-version) when an incremental + bump raised a provider's version. If you set ``DISTRIBUTIONS_LIST`` the incremental flow honors that scope automatically. @@ -398,6 +418,9 @@ changelogs. If there are, you need to add them to PR and classify the changes ma * remove the "Please review" comments generated by the incremental update process * if needed adjust version of provider - in changelog and provider.yaml, in case the new change changes classification of the upgrade (patchlevel/minor/major) +* if a version was bumped, re-run [Update versions of dependent providers to the next + version](#update-versions-of-dependent-providers-to-the-next-version) (the interactive + `--incremental-update` command does not do it for you) In case you want to also release a pre-installed provider that is in ``not-ready`` state (i.e. when you want to release it before you switch their state to ``ready``), you need to pass