From 07fe50e26f9eb17e7b24ba0af9f90e0937837d7d Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Wed, 19 Aug 2026 14:07:36 +0200 Subject: [PATCH 1/2] Document dropping a prepared provider back to doc-only Release managers hit this when review concludes a prepared provider's changes are internal after all: the changelog entry can be corrected, but the version bump and changelog section stay behind and the provider is still built and uploaded. The sequence that actually removes it from the wave - and the marker file that records it - was described nowhere outside the breeze sources. The pre-merge sweep only ever looked for providers missing from a wave, so the opposite direction had nothing watching it in either the manual or the agentic flow. --- .../prepare-providers-documentation/SKILL.md | 17 ++++++ dev/README_RELEASE_PROVIDERS.md | 61 +++++++++++++++++++ 2 files changed, 78 insertions(+) diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md b/.agents/skills/prepare-providers-documentation/SKILL.md index d5d5fe849988f..f3da90b29f646 100644 --- a/.agents/skills/prepare-providers-documentation/SKILL.md +++ b/.agents/skills/prepare-providers-documentation/SKILL.md @@ -901,6 +901,23 @@ git diff --name-only ..HEAD -- '**/provider.yaml' \ - **Bucket B — not in the wave.** The provider has unrecorded commits but no new version section, so it is a candidate to *join*. Classify it (Incremental Phase 3), then take it to **Incremental Phase 3.6**. +- **Bucket C — in the wave but no longer warranting a release.** The sweep + above only finds commits *missing* from a wave; this bucket is the opposite + direction, and nothing else in the flow looks for it. A provider that review + has since concluded is internal-only or documentation-only still carries the + version bump and changelog section written by the initial run, so it would + still be built and uploaded to PyPI. Find these by re-reading the entries of + each in-wave provider's newest changelog section: if every entry is + `Doc-only`, or review reclassified the last remaining non-doc entry as + documentation, the provider should leave the wave. + + Dropping it back is three edits, not a re-run: revert the `provider.yaml` + version bump, remove the new `changelog.rst` section, and write the newest + doc-only commit hash (full hash, trailing newline) into + `providers//docs/.latest-doc-only-change.txt`. **Ask the + release manager before doing it** — taking a provider out of a wave is their + decision, and a `Misc` entry that merely *looks* internal may still be + something they want released. Most Bucket B rows are ordinary noise — repo-wide tooling and test commits that correctly keep a provider out of the release. A Bucket B provider whose diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md index 6e7be44cd4dc0..52919fa9a0570 100644 --- a/dev/README_RELEASE_PROVIDERS.md +++ b/dev/README_RELEASE_PROVIDERS.md @@ -356,6 +356,59 @@ In case you want to also release a pre-installed provider that is in ``not-ready you want to release it before you switch their state to ``ready``), pass ``--include-not-ready-providers``. +### Dropping a prepared provider back to doc-only (no PyPI artifact) + +Two different outcomes are both called "doc-only", and the difference decides whether the provider +gets a PyPI release at all: + +| | What it means | PyPI artifact | +|---|---|---| +| A `doc-only` entry in the changelog | The provider *is* released; one of the entries in the release happens to be documentation | **Yes** | +| The `.latest-doc-only-change.txt` marker | The provider is *not* released at all; only its documentation is republished | **No** | + +The second case comes up when a provider was already prepared with, say, a `Misc` entry, and review +then concludes the change is internal or documentation only, so there is nothing for users to install. +Changing the changelog entry is not enough — the version bump and the changelog stay prepared, and the +provider would still be built and uploaded. The provider has to be dropped back to doc-only: + +1. Undo the prepared changes for that provider — the version bump in `provider.yaml` and the new + changelog section — so the provider is back to its released state: + + ```shell script + git checkout -- providers/PROVIDER/provider.yaml providers/PROVIDER/docs/changelog.rst + ``` + +2. Re-run the documentation preparation for that provider alone: + + ```shell script + breeze release-management prepare-provider-documentation PROVIDER + ``` + +3. Answer **`N`** to `Does the provider: PROVIDER have any changes apart from 'doc-only'?`. + + This writes `providers/PROVIDER/docs/.latest-doc-only-change.txt` and stops preparing that + provider — no version bump, no changelog section, no distribution. + +4. Commit the marker file. It is the only artifact of the whole sequence, and it must be committed + or the next release will prepare the provider again: + + ```shell script + git add providers/PROVIDER/docs/.latest-doc-only-change.txt + ``` + +The marker holds the full commit hash of the latest change that was declared doc-only. On the next +release, the tooling counts commits since that hash rather than since the last release tag, so: + +* if nothing landed since the marker, the provider is skipped with + `The provider has doc-only changes since the last release. Skipping`; +* if something did land, only the commits after the marker are classified, so the changes already + declared doc-only are not offered for classification a second time. + +> [!NOTE] +> The same applies when using the `prepare-providers-documentation` skill — it classifies commits, +> but the decision that a prepared provider should not be released at all is still made by the +> release manager, and is still recorded by this marker file. + ## Update versions of dependent providers to the next version Sometimes when contributors want to use next version of a dependent provider, instead of @@ -436,6 +489,14 @@ following labels to the PR (if they aren't already set from the original PR): * `skip common compat check` * `allow provider dependency bump` +The rebase before merging is also the point to check the wave in the other direction. The incremental +flow looks for commits that are *missing* from the release; it does not look for providers that are in +the release but should no longer be there. If review concluded that a prepared provider's only changes +are internal or documentation, that provider still carries its version bump and changelog section, and +it would still be built and uploaded. Drop it back with [Dropping a prepared provider back to +doc-only](#dropping-a-prepared-provider-back-to-doc-only-no-pypi-artifact) before merging, so the +decision made in review is actually reflected in what gets released. + Once approved, merge it - be careful to do it quickly so that no new PRs are merged for providers in the meantime; if they are, you'd miss them in the changelog. From 14b99925a3e5f1b959ab4e840c39506528be8c35 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Wed, 19 Aug 2026 14:14:18 +0200 Subject: [PATCH 2/2] Add a command to take a prepared provider back out of a release When review concludes that an already-prepared provider has no user-facing changes, correcting its changelog entry leaves the version bump and the changelog section behind, so the provider is still built and uploaded. Undoing that by hand is a restore-rerun-answer-N sequence that release managers repeatedly get wrong, and it is unavailable during an incremental update at all: that mode answers every question with yes, so the prompt that reclassifies a provider as doc-only never appears. --- .../prepare-providers-documentation/SKILL.md | 19 +++-- dev/README_RELEASE_PROVIDERS.md | 39 +++++----- ...agement_prepare-provider-documentation.svg | 78 +++++++++++-------- ...agement_prepare-provider-documentation.txt | 2 +- .../commands/release_management_commands.py | 24 +++++- .../release_management_commands_config.py | 1 + .../provider_documentation.py | 31 ++++++++ .../tests/test_provider_documentation.py | 67 ++++++++++++++++ 8 files changed, 200 insertions(+), 61 deletions(-) diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md b/.agents/skills/prepare-providers-documentation/SKILL.md index f3da90b29f646..cfcfda858170d 100644 --- a/.agents/skills/prepare-providers-documentation/SKILL.md +++ b/.agents/skills/prepare-providers-documentation/SKILL.md @@ -911,13 +911,18 @@ git diff --name-only ..HEAD -- '**/provider.yaml' \ `Doc-only`, or review reclassified the last remaining non-doc entry as documentation, the provider should leave the wave. - Dropping it back is three edits, not a re-run: revert the `provider.yaml` - version bump, remove the new `changelog.rst` section, and write the newest - doc-only commit hash (full hash, trailing newline) into - `providers//docs/.latest-doc-only-change.txt`. **Ask the - release manager before doing it** — taking a provider out of a wave is their - decision, and a `Misc` entry that merely *looks* internal may still be - something they want released. + Drop it back with the dedicated command rather than editing the files by + hand — it restores `provider.yaml` and `changelog.rst` to their released + state and writes the marker in one step: + + ```bash + breeze release-management prepare-provider-documentation --mark-doc-only + ``` + + Then commit `providers//docs/.latest-doc-only-change.txt`. + **Ask the release manager before doing it** — taking a provider out of a wave + is their decision, and a `Misc` entry that merely *looks* internal may still + be something they want released. Most Bucket B rows are ordinary noise — repo-wide tooling and test commits that correctly keep a provider out of the release. A Bucket B provider whose diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md index 52919fa9a0570..96e54c835a62b 100644 --- a/dev/README_RELEASE_PROVIDERS.md +++ b/dev/README_RELEASE_PROVIDERS.md @@ -369,32 +369,29 @@ gets a PyPI release at all: The second case comes up when a provider was already prepared with, say, a `Misc` entry, and review then concludes the change is internal or documentation only, so there is nothing for users to install. Changing the changelog entry is not enough — the version bump and the changelog stay prepared, and the -provider would still be built and uploaded. The provider has to be dropped back to doc-only: +provider would still be built and uploaded. Drop the provider back to doc-only with: -1. Undo the prepared changes for that provider — the version bump in `provider.yaml` and the new - changelog section — so the provider is back to its released state: - - ```shell script - git checkout -- providers/PROVIDER/provider.yaml providers/PROVIDER/docs/changelog.rst - ``` - -2. Re-run the documentation preparation for that provider alone: - - ```shell script - breeze release-management prepare-provider-documentation PROVIDER - ``` +```shell script +breeze release-management prepare-provider-documentation --mark-doc-only PROVIDER [MORE PROVIDERS] +``` -3. Answer **`N`** to `Does the provider: PROVIDER have any changes apart from 'doc-only'?`. +This restores the provider's `provider.yaml` and `changelog.rst` to their released state, then writes +`providers/PROVIDER/docs/.latest-doc-only-change.txt`. No version bump, no changelog section, no +distribution. It needs an explicit list of providers — it takes them out of the release, so it will +not default to every provider. - This writes `providers/PROVIDER/docs/.latest-doc-only-change.txt` and stops preparing that - provider — no version bump, no changelog section, no distribution. +Commit the marker file afterwards. It is the only artifact of the whole sequence, and it must be +committed or the next release will prepare the provider again: -4. Commit the marker file. It is the only artifact of the whole sequence, and it must be committed - or the next release will prepare the provider again: +```shell script +git add providers/PROVIDER/docs/.latest-doc-only-change.txt +``` - ```shell script - git add providers/PROVIDER/docs/.latest-doc-only-change.txt - ``` +Doing it by hand is the same three steps: restore those two files, re-run +`prepare-provider-documentation PROVIDER`, and answer **`N`** to +`Does the provider: PROVIDER have any changes apart from 'doc-only'?`. Note that the interactive +prompt is not reachable during `--incremental-update`, which answers every question with "yes" — +that is what `--mark-doc-only` is for. The marker holds the full commit hash of the latest change that was declared doc-only. On the next release, the tooling counts commits since that hash rather than since the last release tag, so: diff --git a/dev/breeze/doc/images/output_release-management_prepare-provider-documentation.svg b/dev/breeze/doc/images/output_release-management_prepare-provider-documentation.svg index b9c71f9c81aec..2872f68df1c5b 100644 --- a/dev/breeze/doc/images/output_release-management_prepare-provider-documentation.svg +++ b/dev/breeze/doc/images/output_release-management_prepare-provider-documentation.svg @@ -1,4 +1,4 @@ - +