Azure / Azure/azure-rest-api-specs

Update typespec-project.instructions.md to include guidance on committing generated OpenAPI files

Open
#39,960 0 comments 0 reactions 1 assignee Claimed by @praveenkuttappan View on GitHub
AzSDK Tools Agent
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
2d 22h
Merged PRs (30d)
444

Description

## Summary

The instruction file `.github/instructions/typespec-project.instructions.md` provides guidance on creating and modifying TypeSpec projects, including running `tsp compile .` for validation. However, it does not mention that the generated OpenAPI specification files (`openapi.json`) must also be committed alongside the TypeSpec source files.

## Problem

When TypeSpec is compiled, it generates OpenAPI JSON files in the output directories (e.g., `resource-manager///openapi.json` or `data-plane///openapi.json`). Users may not realize these generated files need to be included in their commits and pull requests.

## Recommended Changes

Add the following guidance after the `tsp compile .` instruction (around line 131), or as a new subsection under "Initial migration checklist":

```markdown
## Committing TypeSpec changes

When committing changes to a TypeSpec project, ensure you include **both** the TypeSpec source files and the generated OpenAPI specification files:

1. **TypeSpec source files** (`.tsp` files in the project directory)
2. **Generated OpenAPI files** (`openapi.json` files in the output directories)

The generated files are located in:
- ARM/Resource Manager: `resource-manager////openapi.json`
- Data Plane: `data-plane////openapi.json`

Run `git status` after compilation to verify all modified and new files are staged before committing.
```

## Files Affected

- `.github/instructions/typespec-project.instructions.md`

## Context

This gap was discovered during an AI-assisted workflow where the agent initially only committed the `.tsp` files without the generated `openapi.json` files.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.