Azure / Azure/azure-sdk-tools

Include plain-language rationale when surfacing release approval requirements

Open
#14,614 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent dev inner loop needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

## Problem

During the Azure Key Vault team's first SDK release, the team asked *"where did this link originate from?"* and *why* APIView approval was required. The agent (and existing documentation) assumed prior familiarity with the Azure SDK release process.

First-time service teams lack context on why specific approvals exist and what they protect against. A bare "approval required" message creates confusion and erodes trust in the process.

**Source:** First-time service team feedback (Azure Key Vault)

## Proposed Solution

When the agent surfaces a release requirement (e.g., APIView approval), it should also include:

1. **Why** the approval is required — e.g., *".NET GA releases require APIView sign-off to ensure API surface stability before public release."*
2. **When** it applies — e.g., GA vs. preview, which languages require it
3. **What it protects against** — e.g., accidental breaking changes in the public API surface

This should be a short, plain-language explanation (1–2 sentences) — not a link to a policy document.

## Acceptance Criteria

- [ ] Every blocking release requirement includes a 1–2 sentence rationale explaining *why* it exists
- [ ] The rationale is self-contained — no reliance on external documentation to understand the requirement
- [ ] Rationale differentiates between GA and preview requirements where applicable
- [ ] Language is jargon-free and understandable by a service team with no prior SDK release experience

## User Impact

Reduces confusion and "why do I need this?" questions from service teams. Builds trust in the release process by making requirements transparent rather than opaque. Particularly important for first-time teams who don't have SDK tribal knowledge.

Contributor guide

Open the contributing guide

Research direction

No file or test is named; start by locating the agent code that surfaces blocking release requirements and then trace where requirement applicability for GA, preview, and languages is defined. Add self-contained, jargon-free rationales for each blocking requirement and verify that the acceptance criteria cover the explanation, applicability, and protection provided.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.