Azure / Azure/azure-sdk-tools

[Epic][TypeSpec Authoring] Auto-Scaffold for a brand-new service onboarding

Open
#14,539 1 comment 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent design epic dev inner loop Epic
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
143

Description

hOverall Experience in One Line
> “_Answer 5–7 questions. We’ll scaffold your Azure REST API specs folder + TypeSpec project + first version skeleton, aligned with Azure guidelines._”

Break the experience into 3 stages, aligned with the goals

**Stage 1 - Repo & Versioning Grounding (Folder Structure)**

User Goal - Understand the required folder structure per Azure Service Versioning Guideline without reading a giant doc.
Experience Style - ask 2–3 questions, then instant scaffold + a short visual explanation.
Required Inputs:
- Service type: management plane or data plane
- Service identity: resource provider name (for ARM) or service name (for data plane)
- Initial API version: 2026-01-01, or 2026-01-01-preview
- Is this your first service onboard to azure-rest-api-specs? Yes - create full structure; No - only add new version under existing path
Teaching Moment - [service versioning workflow](https://aka.ms/azbreakingchangespolicy) and [single preview policy](https://learn.microsoft.com/en-us/azure/developer/intro/azure-service-sdk-tool-versioning#preview-versions)

**Stage 2 - Create the TypeSpec Azure Project**

User Goal - Create a new TypeSpec Azure project for Management Plane or Data Plane with minimal friction.
Required Inputs:
- Plane (pre-filled from Stage 1): Management/Data
- Desired languages or SDK targets: all supported languages - Python, Java, JS, Go, .NET
- Top-level namespace / service name (pre-filled from Stage 1)

**Stage 3 - Versioning Strategy + First Versioning Authoring + First Resource Type Adding**

User Goal - Understand how to version with TypeSpec and begin authoring the first version
Required Inputs:
- What lifecycle stage is this API? Under development - preview version; Ready for external partners - preview; Generally available - stable version
- Will you maintain multiple active version at once soon? No; Yes, GA + one Preview
- Short description of first resource types and its operations

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are named. Start by reviewing the three-stage flow and the linked Azure versioning guidance, then define the scaffold outputs and supported answers for each required input. Done means a newcomer can answer the questions and receive the stated folder structure, TypeSpec project, version skeleton, and initial resource scaffold.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.