docs: add Python management SDK release rotation runbook by msyyc · Pull Request #49680 · Azure/azure-sdk-for-python

Yuchao Yan (msyyc) · 2026-10-23T07:12:03Z

Description

Add a Python management SDK release runbook for weekly Go/JavaScript/Python rotation reviewers who are unfamiliar with Python SDK releases.

The runbook covers live PR queues, service-team readiness, automated review results, human approval and re-approval, merge handoff, automatic release follow-up, common partner questions, and escalation. It distinguishes labels and green CI from release readiness, avoids duplicate approvals and review runs, and explains that merging an auto-release PR can publish without a separate manual package-publish approval.

Research preceded the outline and implementation. The 2026-10-23 snapshot included 53 open automated management SDK PRs: 13 drafts and 40 non-drafts. Research also included 20 recent merged PRs, eight detailed PR histories, the Go runbook, and the Python review/release automation.

Add the read-only azsdk-python-mgmt-pr-triage skill to address the question about quickly checking whether a review is active. Link the skill from the runbook. Rotators can ask Copilot to use the skill or run its standalone Python command with authenticated gh; no SDK installation is required.

The skill groups open, non-draft management AutoPRs into five queues: automated review needs triggering, automated review active, human review needed, changes after approval, and author follow-up after approval. It uses workflow-run PR associations, CODEOWNERS and team membership, effective review state, approved commit identity, and author comments. Unknown evidence and incomplete scans produce explicit warnings instead of unsafe trigger recommendations or an empty-backlog claim. It never changes labels, comments, approvals, merges, or releases.

An expected HTTP 403 when reading Azure/azure-arm-sdk-reviewers membership is silently skipped and cached. Individually named CODEOWNERS and readable teams still establish approvals; GitHub's review decision supplies the human-review queue fallback. Other access errors still produce warnings. The skill documents that team-only approvals cannot establish changed-head or author-follow-up queues without a separately verified maintainer.

Address the review's two snapshot races: enumerate workflow runs without status filters and filter completed runs locally, and validate the initial listing's updatedAt against the first PR read before using its review decision. Retain the final collection-window consistency check. Add transition, pagination, stale-listing, and fail-closed regression coverage. Clarify that merge and release follow-up belong to the service team after handoff; rotators assist when requested or escalated, rather than performing mandatory post-approval monitoring.

Validation:

python -m unittest discover -s .github\skills\azsdk-python-mgmt-pr-triage\tests -v — passed, 51 offline tests covering workflow activity, freshness, ownership, approval invalidation, changed heads, author follow-ups, pagination, filtering, incomplete scans, the team-membership 403 fallback, active-status transitions, and stale listing decisions.
python -m black --check --line-length 120 .github\skills\azsdk-python-mgmt-pr-triage\scripts\triage_prs.py .github\skills\azsdk-python-mgmt-pr-triage\tests\test_triage_prs.py — passed.
python .github\skills\azsdk-python-mgmt-pr-triage\scripts\triage_prs.py --package azure-mgmt-iothub — passed; package version and missing human approval verified against the PR's version diff and reviews.
python .github\skills\azsdk-python-mgmt-pr-triage\scripts\triage_prs.py — passed; scanned 36 open non-draft management AutoPRs on 2026-10-27 without verification warnings. The six human-review entries ([AutoPR azure-mgmt-hybridcompute]-generated-from-SDK Generation - Python-7001062 #49709, [AutoPR azure-mgmt-sovereign]-generated-from-SDK Generation - Python-7030648 #49705, [AutoPR azure-mgmt-migrate]-generated-from-SDK Generation - Python-6746547 #48758, [AutoPR azure-mgmt-monitor]-generated-from-SDK Generation - Python-6996283 #49699, [AutoPR azure-mgmt-iothub]-generated-from-SDK Generation - Python-6994850 #49684, [AutoPR azure-mgmt-managednetworkfabric]-generated-from-SDK Generation - Python-7018490 #49662), unchanged approved heads, and recent author-comment results agreed with independently collected GraphQL evidence. Direct comment inspection confirmed missing automated reviews on [AutoPR azure-mgmt-hybridcompute]-generated-from-SDK Generation - Python-7001062 #49709 and [AutoPR azure-mgmt-sovereign]-generated-from-SDK Generation - Python-7030648 #49705. A separate paginated workflow-run query confirmed no active reviews.
git diff --check — passed.
gh run watch 40442150568 --repo Azure/azure-sdk-for-python --exit-status --interval 10 — passed; Verify Links succeeded on commit f6ec720e20 after replacing the runbook's relative skill link with an absolute GitHub URL.

The live permission regression also passed: the scanner was reapplied to all 34 PRs with only the reported team-membership HTTP 403 injected into its GitHub CLI wrapper. It issued one denied membership request, cached the failure, exited 0, and produced no verification warnings. Its four human-review entries matched an independent GitHub review-decision query.

The skill's remaining relative Markdown link resolved. The runbook now uses an absolute HTTPS skill link, as required by CI link guidance. Both Python files parsed using Python 3.10 grammar. SDK builds, package tests, and Sphinx were not run: this PR changes contributor tooling and documentation, not SDK packages.

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

No package changelog is needed: this PR changes contributor tooling and documentation only.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

No SDK runtime behavior changes. Contributor-tool tests and live read-only validation are described above.

Fixes #49651 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f63e6e2b-238f-4cd4-952e-43d460067877

azure-pipelines · 2026-10-23T07:12:45Z

Azure Pipelines: Successfully started running 1 pipeline(s). 9 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Address review feedback: write for reviewers unfamiliar with Python releases, explain the maintainer-applied review label and bot follow-up, and remove changes to existing documentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f63e6e2b-238f-4cd4-952e-43d460067877

github-actions · 2026-10-23T08:13:53Z

[Pilot] PR Pipeline Failure Analysis

What failed

1. CSpell spelling check — Azure Pipeline python - pullrequest (build 6993013)

doc/dev/mgmt/mgmt-release-rotation-runbook.md:19:13 — Unknown word Chenxi.

2. Broken relative links — GitHub Actions Verify Links

7 of 18 checked links in doc/dev/mgmt/mgmt-release-rotation-runbook.md are broken:
- ../../../.github/CODEOWNERS
- ../../../.github/workflows/mgmt-sdk-pr-review.md
- ../../../.github/instructions/reviewer/management.instructions.md
- sdk-breaking-changes-guide.md
- ../../../eng/pipelines/templates/stages/archetype-python-release.yml
- ../release.md#releasing-through-unified-pipelines
- tests.md

Relevant pipeline output

##[error]doc/dev/mgmt/mgmt-release-rotation-runbook.md:19:13 - Unknown word (Chenxi)
##[error]Spelling errors detected. To correct false positives or learn about spell checking see: https://aka.ms/azsdk/engsys/spellcheck

'(redacted) has 7 broken link(s):
  ../../../.github/CODEOWNERS
  ../../../.github/workflows/mgmt-sdk-pr-review.md
  ../../../.github/instructions/reviewer/management.instructions.md
  sdk-breaking-changes-guide.md
  ../../../eng/pipelines/templates/stages/archetype-python-release.yml
  ../release.md#releasing-through-unified-pipelines
  tests.md
Checked 18 links with 1 broken link(s) found.

Recommended next steps

Add Chenxi to the repo's cspell custom word list (e.g. .vscode/cspell.json), or reword the line to avoid the unrecognized term.
Fix each broken relative link in doc/dev/mgmt/mgmt-release-rotation-runbook.md: some targets exist in the repo but at a different relative depth than referenced (.github/CODEOWNERS, eng/pipelines/templates/stages/archetype-python-release.yml); others reference files that don't appear to exist at all under .github/workflows/, .github/instructions/reviewer/, or doc/dev/ (mgmt-sdk-pr-review.md, management.instructions.md, sdk-breaking-changes-guide.md, release.md, tests.md) — locate the correct existing target or remove/replace the reference.
See https://aka.ms/ci-fix

Automated fix: Requested

Generated by Pipeline Analysis Next Steps · copilot · sonnet50 · 43.9 AIC · ⌖ 0.564 AIC · ⊞ 8.9K · ◷

Use one PR queue, focus review on bot findings and CI, clarify re-approval, and fix documentation links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1be9a77a-185e-4a49-bb2e-9f1f4d952fcc

Direct release pipeline failures to Engineering System support and remove US-based coverage guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1be9a77a-185e-4a49-bb2e-9f1f4d952fcc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1be9a77a-185e-4a49-bb2e-9f1f4d952fcc

Copilot

🟢 Approval recommended

The documentation is consistent with the reviewed automation and release guidance, with no blocking issues identified.

No open issues 🎉

What changed in this PR

Adds a standalone Python management SDK release runbook for cross-language rotation reviewers, addressing #49651 without changing existing documentation or SDK behavior.

Changes:

Provides a live PR queue and guidance for readiness checks, bot reviews, approval, and re-approval.
Explains merge handoff, automatic publication, release verification, and manual-release boundaries.
Covers common partner questions, escalation paths, and reviewer responsibilities.

File	Description
`doc/dev/mgmt/mgmt-release-rotation-runbook.md`	Adds end-to-end guidance for the Python management SDK release rotation.

_{Review effort: Balanced}

Link release rotators to workflow-aware PR queues with offline tests and standalone usage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Verified snapshot and status-transition races can produce duplicate-review recommendations or incorrect no-action reports.

2 open issues

_{Review effort: Balanced}

Keep named CODEOWNER approvals and use GitHub review decisions when the optional reviewer team cannot be read. Cache the expected denial and retain warnings for other errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

Workflow activity and approval-state snapshot races can produce duplicate-review recommendations or omit PRs needing human attention.

2 open issues

_{Review effort: Balanced}

Copilot

🔵 Needs a closer look

Snapshot-consistency races can miss active reviews or omit PRs needing human attention without verification warnings.

2 open issues

_{Review effort: Balanced}

Scan workflow runs without status filters and reject stale initial PR snapshots. Add race regressions and clarify service-team ownership after review handoff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟢 Approval recommended

No active review issues are recorded for the release runbook and read-only triage tooling.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced}

Comply with Verify Links guidance for documentation outside relative-link exemptions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟢 Approval recommended

No active review issues are reported for the release-rotation runbook and read-only PR triage tooling.

No open issues 🎉

_{Review effort: Balanced}

Copilot

🟢 Approval recommended

No active review issues were identified for the release-rotation runbook and read-only PR triage tooling.

No open issues 🎉

_{Review effort: Balanced}

Clarify reviewer roles, active workflow checks, approval comparisons, and explicit manual-release intent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8560e756-c30b-4ed8-b15e-f1b8ddeec83e

Copilot

🟢 Approval recommended

No active review issues are reported for the release-rotation runbook and read-only PR triage tooling.

No open issues 🎉

_{Review effort: Balanced}

docs: add Python management SDK release rotation runbook

323cca5

Fixes #49651 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f63e6e2b-238f-4cd4-952e-43d460067877

Yuchao Yan (msyyc) commented Oct 23, 2026

View reviewed changes

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Yuchao Yan (msyyc) commented Oct 23, 2026

View reviewed changes

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Yuchao Yan (msyyc) and others added 2 commits October 23, 2026 17:45

docs: simplify management release rotation triage

a1a5059

Use one PR queue, focus review on bot findings and CI, clarify re-approval, and fix documentation links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1be9a77a-185e-4a49-bb2e-9f1f4d952fcc

Yuchao Yan (msyyc) marked this pull request as ready for review October 23, 2026 10:05

Yuchao Yan (msyyc) requested review from a team, jenny (JennyPng), Daniel Jurek (danieljurek) and Libba Lawrence (l0lawrence) as code owners October 23, 2026 10:05

Copilot AI balanced review requested due to automatic review settings October 23, 2026 10:05

docs: mark release workflow sections as ordered steps

519b04d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1be9a77a-185e-4a49-bb2e-9f1f4d952fcc

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 23, 2026 10:06

View session

Copilot AI reviewed Oct 23, 2026

View reviewed changes

Chenjie Shi (tadelesh) reviewed Oct 26, 2026

View reviewed changes

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Add read-only management SDK PR triage skill

beb4983

Link release rotators to workflow-aware PR queues with offline tests and standalone usage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 26, 2026 09:22

Yuchao Yan (msyyc) requested review from a team and Laia Patiño (laiapat) as code owners October 26, 2026 09:22

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 26, 2026 09:22

View session

Remove management triage skill routing from AGENTS.md

e190d3c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread .github/skills/azsdk-python-mgmt-pr-triage/scripts/triage_prs.py Resolved

Comment thread .github/skills/azsdk-python-mgmt-pr-triage/scripts/triage_prs.py Resolved

Copilot AI balanced review requested due to automatic review settings October 26, 2026 09:32

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 26, 2026 09:33

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 26, 2026 09:38

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 26, 2026 09:38

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Fix management PR triage snapshot races

1bb6e77

Scan workflow runs without status filters and reject stale initial PR snapshots. Add race regressions and clarify service-team ownership after review handoff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 27, 2026 02:01

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 27, 2026 02:02

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Use absolute skill link in management release runbook

f6ec720

Comply with Verify Links guidance for documentation outside relative-link exemptions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 27, 2026 03:04

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 27, 2026 03:05

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Merge branch 'main' into docs/python-mgmt-release-rotation-49651

2ca63a4

Copilot AI balanced review requested due to automatic review settings October 27, 2026 03:45

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 27, 2026 03:46

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Chenxi Jiang (ChenxiJiang333) reviewed Oct 27, 2026

View reviewed changes

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

Comment thread doc/dev/mgmt/mgmt-release-rotation-runbook.md Resolved

docs: clarify management release rotation guidance

cef3d34

Clarify reviewer roles, active workflow checks, approval comparisons, and explicit manual-release intent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8560e756-c30b-4ed8-b15e-f1b8ddeec83e

Copilot AI balanced review requested due to automatic review settings October 27, 2026 06:50

Copilot started reviewing on behalf of Yuchao Yan (msyyc) October 27, 2026 06:50

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Chenxi Jiang (ChenxiJiang333) approved these changes Oct 27, 2026

View reviewed changes

Yuchao Yan (msyyc) merged commit cf17c42 into main Oct 27, 2026
21 checks passed

Yuchao Yan (msyyc) deleted the docs/python-mgmt-release-rotation-49651 branch October 27, 2026 07:27

Conversation

Yuchao Yan (msyyc) commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

azure-pipelines Bot commented Oct 23, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 23, 2026

What failed

Recommended next steps

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Yuchao Yan (msyyc) commented Oct 23, 2026 •

edited

Loading