Azure / Azure/azure-rest-api-specs
Update typespec-project.instructions.md to include guidance on committing generated OpenAPI files
- 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
Assessment
This issue has not been assessed yet.