Skip to content

Commit cdc2c65

Browse files
Copilotdolauli
Copilot
and
dolauli
authored
Add comprehensive GitHub Copilot instructions for AutoRest PowerShell development (#1516)
* Initial plan * Add comprehensive GitHub Copilot instructions with full validation Co-authored-by: dolauli <[email protected]> * Update Node.js installation instructions --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: dolauli <[email protected]> Co-authored-by: Xiaogang <[email protected]>
1 parent 43d095c commit cdc2c65

File tree

1 file changed

+133
-0
lines changed

1 file changed

+133
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# AutoRest PowerShell Generator
2+
3+
AutoRest PowerShell is a monorepo containing generators that create PowerShell cmdlets from OpenAPI specifications. The repository uses Rush.js for monorepo management and contains multiple packages including the core AutoRest PowerShell generator and TypeSpec PowerShell tools.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Initial Setup and Dependencies
10+
- Install Node.js LTS (20.19.5 recommended): `curl -fsSL https://nodejs.org/dist/v20.19.5/node-v20.19.5-linux-x64.tar.xz | tar -xJ -C /usr/local --strip-components=1`
11+
- Install Rush.js globally: `npm install -g @microsoft/[email protected]`
12+
- Install AutoRest globally: `npm install -g autorest@latest`
13+
- Verify PowerShell is available (6.0+ required): `pwsh -version`
14+
- Verify .NET SDK is available (2.0+ required): `dotnet --version`
15+
16+
### Bootstrap and Build Process
17+
- Sync package versions: `rush sync-versions` -- takes 1 second. Always run first.
18+
- Install dependencies: `rush update` -- takes 20 seconds. NEVER CANCEL.
19+
- Build all projects: `rush rebuild` -- takes 8 seconds. NEVER CANCEL.
20+
21+
### Testing and Validation
22+
- Run unit tests: `cd powershell && npm test` -- takes 1 second. Should show 3 passing tests.
23+
- Run linting: `cd powershell && npm run eslint` -- instant. Must pass without errors.
24+
- **CRITICAL**: Run comprehensive SDK validation: `cd tests-upgrade/tests-sdk1-support && pwsh ./AutoRestSupportSdkTest.ps1 -AllowList -SkipCsharp` -- takes 4 minutes. NEVER CANCEL. Set timeout to 10+ minutes. Should show 52 test cases all passing with "Equal" status.
25+
26+
### Development Workflow
27+
- Always run the bootstrap steps first before making changes
28+
- Build incrementally: `cd powershell && npm run build` for quick iteration
29+
- Watch mode for continuous compilation: `cd powershell && npm run watch`
30+
- Test local generator: `autorest --use:./powershell --powershell --input-file:./samples/Xkcd/xkcd.yaml --output-folder:/tmp/test-output` -- takes 4 seconds. Should generate 180 files.
31+
32+
## Validation
33+
34+
**CRITICAL**: Always run the following validation sequence after making changes:
35+
36+
1. **Build validation**: `rush rebuild` -- must complete without errors
37+
2. **Unit test validation**: `cd powershell && npm test` -- all 3 tests must pass
38+
3. **Code quality validation**: `cd powershell && npm run eslint` -- must pass without warnings
39+
4. **Generator functionality validation**: Test local AutoRest generation as shown above
40+
5. **Comprehensive SDK validation**: Run the full SDK support test as shown above -- all 52 test cases must pass
41+
42+
**MANUAL VALIDATION REQUIREMENT**: After building, you MUST test actual functionality:
43+
- Generate a PowerShell module from a sample OpenAPI spec
44+
- Verify the generated module contains expected cmdlets and functions
45+
- Check that generated PowerShell files are syntactically correct
46+
- Ensure the module can be imported successfully with `Import-Module`
47+
48+
### Key Validation Scenarios
49+
- **Login/Authentication Flow**: Generate a module with authentication and test cmdlet parameter binding
50+
- **CRUD Operations**: Generate a module with GET/POST/PUT/DELETE operations and verify all cmdlets are created
51+
- **Complex Models**: Test with specifications containing nested objects and arrays
52+
- **Error Handling**: Verify generated cmdlets handle API errors appropriately
53+
54+
## Common Tasks
55+
56+
### Repository Structure
57+
```
58+
.
59+
├── .github/workflows/ # CI/CD pipelines
60+
├── .scripts/ # PowerShell automation scripts
61+
├── docs/ # Documentation
62+
├── packages/
63+
│ └── typespec-powershell/ # TypeSpec PowerShell tools
64+
├── powershell/ # Main AutoRest PowerShell generator
65+
├── samples/ # Example OpenAPI specifications
66+
├── tests/ # Legacy test specifications
67+
├── tests-upgrade/ # Current test suites
68+
│ └── tests-sdk1-support/ # Comprehensive SDK validation tests
69+
├── package.json # Root package configuration
70+
├── rush.json # Rush monorepo configuration
71+
└── tsconfig.json # TypeScript configuration
72+
```
73+
74+
### Key Projects
75+
- **@autorest/powershell**: Main PowerShell cmdlet generator (./powershell/)
76+
- **@azure-tools/typespec-powershell**: TypeSpec to PowerShell tools (./packages/typespec-powershell/)
77+
- **emitter-test**: Test project for emitter functionality (./tests-upgrade/tests-emitter/)
78+
79+
### Important Files and Directories
80+
- `./powershell/main.ts` - Entry point for AutoRest PowerShell generator
81+
- `./powershell/generators/` - Core generation logic
82+
- `./powershell/cmdlets/` - Cmdlet generation templates
83+
- `./tests-upgrade/tests-sdk1-support/` - Comprehensive test suite with 52 test cases
84+
- `./.scripts/` - PowerShell scripts for testing and validation
85+
- `./docs/development.md` - Developer setup instructions
86+
87+
### CI/CD Pipeline Requirements
88+
- All builds must pass: `rush rebuild`
89+
- All unit tests must pass: `npm test`
90+
- ESLint must pass: `npm run eslint`
91+
- SDK support test must pass: All 52 test cases in tests-sdk1-support
92+
- Generated PowerShell modules must be syntactically valid
93+
94+
### Debugging
95+
- Use VS Code with the provided configuration (`.vscode/launch.json`)
96+
- Debug AutoRest generation: `autorest --use:./powershell --powershell.debugger --input-file:<spec>`
97+
- Debug with Node.js: `node --inspect-brk ./powershell/dist/main.js`
98+
- Monitor Rush operations: `rush rebuild --verbose`
99+
100+
### Common Commands Reference
101+
```bash
102+
# Essential setup
103+
rush sync-versions && rush update && rush rebuild
104+
105+
# Development cycle
106+
cd powershell && npm run build && npm test && npm run eslint
107+
108+
# Test local generator
109+
autorest --use:./powershell --powershell --input-file:./samples/Xkcd/xkcd.yaml --output-folder:/tmp/test-output
110+
111+
# Comprehensive validation
112+
cd tests-upgrade/tests-sdk1-support && pwsh ./AutoRestSupportSdkTest.ps1 -AllowList -SkipCsharp
113+
114+
# Watch mode for development
115+
cd powershell && npm run watch
116+
```
117+
118+
### Timing Expectations
119+
- **NEVER CANCEL**: rush update takes 20 seconds
120+
- **NEVER CANCEL**: rush rebuild takes 8 seconds
121+
- **NEVER CANCEL**: SDK support test takes 4 minutes
122+
- **NEVER CANCEL**: Any command taking longer than expected should be allowed to complete
123+
- npm test: 1 second
124+
- npm run eslint: instant
125+
- AutoRest generation: 4 seconds
126+
127+
## CRITICAL REMINDERS
128+
- **ALWAYS** run `rush sync-versions && rush update && rush rebuild` before starting work
129+
- **ALWAYS** validate changes with the full SDK support test - it catches integration issues
130+
- **NEVER CANCEL** long-running commands - builds and tests need time to complete
131+
- **DO NOT** use `rush test` - it has configuration issues, use specific test commands instead
132+
- **ALWAYS** test generated PowerShell modules manually to ensure they work correctly
133+
- **ALWAYS** run ESLint before committing - the CI pipeline will fail otherwise

0 commit comments

Comments
 (0)