Include plain-language rationale when surfacing release approval requirements
- 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
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