diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md b/.agents/skills/prepare-providers-documentation/SKILL.md index d5d5fe849988f..cfcfda858170d 100644 --- a/.agents/skills/prepare-providers-documentation/SKILL.md +++ b/.agents/skills/prepare-providers-documentation/SKILL.md @@ -901,6 +901,28 @@ 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. + + 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 6e7be44cd4dc0..96e54c835a62b 100644 --- a/dev/README_RELEASE_PROVIDERS.md +++ b/dev/README_RELEASE_PROVIDERS.md @@ -356,6 +356,56 @@ 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. Drop the provider back to doc-only with: + +```shell script +breeze release-management prepare-provider-documentation --mark-doc-only PROVIDER [MORE PROVIDERS] +``` + +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. + +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: + +```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: + +* 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 +486,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. 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 @@ - +