microsoft/typespec
Publicmirrored from https://github.com/microsoft/typespecAvailable
.github/copilot-instructions.md
122lines · modecode
| 1 | # TypeSpec Copilot Instructions |
| 2 | |
| 3 | **ALWAYS follow these instructions first and only fall back to additional search and context gathering if the information here is incomplete or found to be in error.** |
| 4 | |
| 5 | TypeSpec is a language for defining cloud service APIs and shapes. This monorepo contains the TypeSpec compiler, standard library packages, tools, documentation, and various language client emitters. |
| 6 | |
| 7 | ## Essential Setup and Build Commands |
| 8 | |
| 9 | ### Prerequisites and Installation |
| 10 | |
| 11 | - Install Node.js 20 LTS: `curl -fsSL https://nodejs.org/dist/v20.19.4/node-v20.19.4-linux-x64.tar.xz | tar -xJ --strip-components=1 -C /usr/local` |
| 12 | - Install pnpm globally: `npm install -g pnpm` |
| 13 | - Install dependencies: `pnpm install` (takes ~1.5 minutes) |
| 14 | - Install Playwright browsers (optional for UI testing): `npx playwright install` |
| 15 | |
| 16 | ### Building the Project |
| 17 | |
| 18 | - **CRITICAL**: Build the entire project: `pnpm build` (takes ~7 minutes, NEVER CANCEL - set timeout to 15+ minutes) |
| 19 | - Build in watch mode for development: `pnpm watch` |
| 20 | - Build specific package: `pnpm -r --filter "<package-name>..." build` |
| 21 | - Clean build artifacts: `pnpm clean` |
| 22 | |
| 23 | ### Testing and Validation |
| 24 | |
| 25 | - **CRITICAL**: Run all tests: `pnpm test` (takes ~5 minutes, NEVER CANCEL - set timeout to 10+ minutes) |
| 26 | - Run E2E tests: `pnpm test:e2e` and `node e2e/e2e-tests.js` (~1 minute) |
| 27 | - Run tests with coverage: `pnpm test:ci` |
| 28 | - Run tests in watch mode (in specific package): `pnpm test:watch` |
| 29 | |
| 30 | ### Code Quality |
| 31 | |
| 32 | - Check formatting: `pnpm format:check` (~1 minute) |
| 33 | - Format code: `pnpm format` |
| 34 | - Run linting: `pnpm lint` (~1 minute) |
| 35 | - Fix lint issues: `pnpm lint:fix` |
| 36 | |
| 37 | ### Essential TypeSpec Development Workflow |
| 38 | |
| 39 | 1. **ALWAYS** run the full build process after repository clone: `pnpm install && pnpm build` |
| 40 | 2. Start watch mode: `pnpm watch` |
| 41 | 3. Test TypeSpec compilation works: |
| 42 | |
| 43 | ```bash |
| 44 | # Create test project |
| 45 | mkdir test-tsp && cd test-tsp |
| 46 | echo 'import "@typespec/rest"; import "@typespec/openapi3"; op ping(): void;' > main.tsp |
| 47 | echo '{"dependencies": {"@typespec/compiler": "latest", "@typespec/rest": "latest", "@typespec/openapi3": "latest"}}' > package.json |
| 48 | |
| 49 | # Install and compile |
| 50 | /path/to/typespec/packages/compiler/cmd/tsp.js install |
| 51 | /path/to/typespec/packages/compiler/cmd/tsp.js compile main.tsp --emit @typespec/openapi3 |
| 52 | ``` |
| 53 | |
| 54 | 4. Always format and lint before completing changes: `pnpm format && pnpm lint:fix` |
| 55 | |
| 56 | ## Repository Structure |
| 57 | |
| 58 | ### Key Packages (packages/) |
| 59 | |
| 60 | - **compiler**: Core TypeSpec compiler and CLI tool |
| 61 | - **http, rest, openapi3**: Standard HTTP/REST API libraries |
| 62 | - **versioning**: API versioning support |
| 63 | - **json-schema**: JSON Schema emitter |
| 64 | - **prettier-plugin-typespec**: Code formatting support |
| 65 | - **typespec-vscode, typespec-vs**: Editor extensions |
| 66 | - **playground**: Interactive TypeSpec playground |
| 67 | - **website**: Documentation website (typespec.io) |
| 68 | |
| 69 | ### Important Directories |
| 70 | |
| 71 | - `/packages/`: All TypeSpec packages and libraries |
| 72 | - `/e2e/`: End-to-end integration tests |
| 73 | - `/website/`: Documentation website source |
| 74 | - `/eng/`: Build engineering and automation scripts |
| 75 | - `/.github/workflows/`: CI/CD pipeline definitions |
| 76 | |
| 77 | ## Manual Validation After Changes |
| 78 | |
| 79 | **ALWAYS perform these validation steps after making changes:** |
| 80 | |
| 81 | 1. **Basic functionality test**: Create and compile a simple TypeSpec file as shown above |
| 82 | 2. **Build validation**: Run full build to ensure no build breaks: `pnpm build` |
| 83 | 3. **Test validation**: Run relevant tests: `pnpm test` |
| 84 | 4. **Code quality**: Ensure formatting and linting pass: `pnpm format:check && pnpm lint` |
| 85 | |
| 86 | ## Website Development |
| 87 | |
| 88 | - Navigate to website: `cd website` |
| 89 | - Start development server: `pnpm start` (runs on port 4321) |
| 90 | - Build website: `pnpm build` |
| 91 | - The website includes documentation, API references, and the playground |
| 92 | |
| 93 | ## Critical Timing and Performance Notes |
| 94 | |
| 95 | - **NEVER CANCEL** long-running commands - builds can take 7+ minutes, tests 5+ minutes |
| 96 | - Set explicit timeouts: Build commands need 15+ minutes, test commands need 10+ minutes |
| 97 | - Package installation: ~1.5 minutes |
| 98 | - Full rebuild from clean state: ~7 minutes |
| 99 | - Full test suite: ~5 minutes |
| 100 | - Lint check: ~1 minute |
| 101 | - E2E tests: ~1 minute |
| 102 | |
| 103 | ## Common Development Tasks |
| 104 | |
| 105 | - Add change description: `pnpm change add` |
| 106 | - Generate external signatures: `pnpm gen-compiler-extern-signature` |
| 107 | - Regenerate samples: `pnpm regen-samples` |
| 108 | - Regenerate docs: `pnpm regen-docs` |
| 109 | - Sync dependency versions: `pnpm fix-version-mismatch` |
| 110 | |
| 111 | ## Troubleshooting |
| 112 | |
| 113 | - If builds fail with watch mode conflicts, run: `pnpm clean && pnpm build` |
| 114 | - For installation issues, try: `pnpm install-conflict` |
| 115 | - If TypeScript compilation fails, check that compiler built first: `pnpm -r --filter "@typespec/compiler" build` |
| 116 | - For VS Code extension development, ensure you have the workspace open at the repository root |
| 117 | |
| 118 | ## Available Task Instructions |
| 119 | |
| 120 | - [Testserver Generation](./prompts/testserver-generation.md): Instructions for generating TypeSpec HTTP spec test servers |
| 121 | - [http-client-csharp Development](./prompts/http-client-csharp-development.md): Instructions for developing the C# HTTP client |
| 122 | - [http-client-java Development](../packages/http-client-java/.github/copilot-instructions.md): Instructions for developing the TypeSpec library for Java client. |
| 123 | |