This is an automated email from the ASF dual-hosted git repository.
shahar1 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 832ecf89a36 Document breaking-change changelog notes in provider docs
skill (#68738)
832ecf89a36 is described below
commit 832ecf89a36e142afff399356322cbb932812096
Author: Shahar Epstein <[email protected]>
AuthorDate: Fri Jun 19 17:34:16 2026 +0300
Document breaking-change changelog notes in provider docs skill (#68738)
The prepare-providers-documentation skill only told the agent to add a
top-of-version note for the Airflow min-version bump case, so a release
shipping a behavioural breaking change got the bullet but no explanation
of what breaks or how to adapt. The repository changelog convention asks
for exactly such an explanation whenever there is a breaking change, so
make the skill require it for every breaking classification.
---
.../prepare-providers-documentation/SKILL.md | 24 +++++++++++++++++++---
1 file changed, 21 insertions(+), 3 deletions(-)
diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md
b/.agents/skills/prepare-providers-documentation/SKILL.md
index d3c90f546a7..c4838af4df3 100644
--- a/.agents/skills/prepare-providers-documentation/SKILL.md
+++ b/.agents/skills/prepare-providers-documentation/SKILL.md
@@ -453,9 +453,23 @@ Doc-only
Rules:
-- Include the `.. note::` block **only** when the version bump was driven by
- a `min_airflow_bump` (or by a `breaking` whose breaking aspect is the
- Airflow min bump).
+- A `.. note::` block at the top of the version section (directly under the
+ `<dots>` underline, before the first `~~~` header) is used in two distinct
+ situations. Include it whenever **either** applies — combine the wording
+ into a single note, or stack two notes, when both do:
+ - **Airflow min-version bump** — when the bump was driven by a
+ `min_airflow_bump` (or by a `breaking` whose breaking aspect *is* the
+ Airflow min bump), use the support-policy wording shown in the skeleton.
+ - **Breaking change** — for **every** `breaking` classification (major
+ bump, including a `0.x` minor that ships a breaking change), add a note
+ explaining *what* breaks and *how users should adapt* (the migration
+ path). Write it from the PR description and the actual diff, not as a
+ restatement of the commit subject — the reader must learn how to react
+ without opening the PR. This mirrors the standing changelog convention
+ ("only add notes … when there are some breaking changes and you want to
+ add an explanation to the users on how they are supposed to deal with
+ them"). The bullet under `Breaking changes` still lists the commit
+ subject as usual; the note is in addition to it, not a replacement.
- Drop a section entirely if it has no entries (e.g. no `Breaking changes`
section if there were none — don't leave an empty header).
- The `.. Below changes are excluded ...` block at the end is required even
@@ -670,6 +684,10 @@ If you re-bumped the version in Incremental Phase 3.5,
also add or remove the
`.. note::` block about the Airflow min version requirement to match the
new bump kind.
+If a new commit is classified `breaking`, add (or extend) a `.. note::` at the
+top of the version section explaining what breaks and how users should adapt,
+exactly as in the breaking-change note rule in Phase 4b.
+
### Incremental Phase 5 — Validate
Same as Phase 5 of the initial run plus an extra check: confirm there are
