From 0555c856f8a89fefb3d2bd96866bbd2cea1698f8 Mon Sep 17 00:00:00 2001 From: Shahar Epstein <60007259+shahar1@users.noreply.github.com> Date: Tue, 16 Jun 2026 23:36:05 +0300 Subject: [PATCH] Warn release managers to verify prepare-providers-documentation output The provider release docs presented the AI-driven skill as "the recommended way" to classify commits, which oversells it: its classifications are LLM-generated and must be checked by the release manager, the run is long and token-heavy enough to be impractical without a high-capacity plan, and release managers who do not use AI tooling have no path through that recommendation. Reframe it as an optional aid alongside the interactive breeze command and spell out these caveats explicitly. --- dev/README_RELEASE_PROVIDERS.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md index 04b25799e9c86..36841800f72e9 100644 --- a/dev/README_RELEASE_PROVIDERS.md +++ b/dev/README_RELEASE_PROVIDERS.md @@ -196,7 +196,7 @@ First thing that release manager has to do is to convert commits for each provid and update version of the provider to a target version - depending on type of changes implemented in the providers. -The recommended way to do this is via the **`prepare-providers-documentation` skill** loaded by an +One option for doing this is the **`prepare-providers-documentation` skill** loaded by an agentic coding framework (e.g. Claude Code or OpenAI Codex CLI), which replaces the manual commit-by-commit classification step of `breeze release-management prepare-provider-documentation` with AI-driven classification. The skill inspects every PR (using @@ -204,6 +204,24 @@ sub-agents per PR for thorough analysis), pays special attention to potentially reading the actual diff (not just the commit message or PR labels), scopes multi-provider PRs to the slice that touched the current provider, and asks the release manager only when genuinely uncertain. +> [!WARNING] +> The skill is an **optional** aid, not a required or default part of the release process. The +> interactive `breeze release-management prepare-provider-documentation` command (see +> [Falling back to interactive breeze](#falling-back-to-interactive-breeze)) remains the baseline, +> and release managers who do not use AI tooling should use that command directly — this skill is +> not for them. If you do use the skill, keep the following in mind: +> +> * **You must verify its output.** The version bumps and changelog entries it produces are +> generated by an LLM and are **not authoritative** — the release manager is responsible for +> reviewing every generated entry (especially breaking-change classification and version bumps) +> before merging the release PR. Treat the skill's output as a first draft to be checked, not a +> final answer. +> * **It runs for a long time and consumes a lot of tokens.** Classifying a full release wave with +> per-PR sub-agents can take a while and burn through a large amount of model tokens. Because of +> that, it is hard to recommend without a high-capacity plan (e.g. Claude Max, or an equivalent +> GitHub Copilot / OpenAI tier). On a metered or low-quota plan the cost may be significant and +> the run may not complete. + **Prerequisites:** running this skill requires an agentic coding environment with the [GitHub MCP server](https://github.com/github/github-mcp-server) configured — the skill reads PR diffs, lists commits, and (with maintainer confirmation) edits files via these tools. Two well-known