Skip to content

Commit 4fbdb6e

Browse files
Copilotzhoxing-ms
Copilot
and
zhoxing-ms
committed
Create comprehensive .github/copilot-instructions.md for Azure CLI development
Co-authored-by: zhoxing-ms <16612065+zhoxing-ms@users.noreply.github.com>
1 parent 04c5d30 commit 4fbdb6e

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Azure CLI Copilot Development Instructions
2+
3+
## Repository Overview
4+
5+
**Microsoft Azure CLI** is the official command-line interface for Microsoft Azure cloud services. This is a large Python-based repository (~4 core modules + extensive tooling) that provides a comprehensive multi-platform CLI experience.
6+
7+
- **Primary Language**: Python 3.9-3.12 (3.12 recommended)
8+
- **Repository Type**: Command-line interface with command modules
9+
- **Target Platforms**: Windows, Linux, macOS
10+
- **Package Formats**: MSI, DEB, RPM, Docker, Homebrew, PyPI wheels
11+
- **Development Tool**: `azdev` (Azure Developer Tool) - **DO NOT use the deprecated `dev_setup.py`**
12+
13+
## Essential Development Setup
14+
15+
### Prerequisites
16+
- Python 3.9-3.12 (3.12 preferred)
17+
- Git
18+
- Virtual environment support
19+
20+
### Quick Start (ALWAYS follow this order)
21+
```bash
22+
# 1. Create and activate virtual environment
23+
python -m venv env
24+
source env/bin/activate # Linux/Mac
25+
# env\Scripts\activate # Windows
26+
27+
# 2. Upgrade pip first
28+
python -m pip install --upgrade pip
29+
30+
# 3. Install azdev (may take 2-3 minutes)
31+
pip install azdev
32+
33+
# 4. Setup development environment (may take 5-10 minutes)
34+
azdev setup -c
35+
36+
# 5. Verify installation
37+
az --version
38+
```
39+
40+
**Network Issues**: If pip install fails with timeout errors, retry with `--timeout 300` or `--retries 10`. This is common in this repository.
41+
42+
## Build and Validation Commands
43+
44+
### Core Development Commands
45+
```bash
46+
# Install all modules from source (alternative to azdev setup)
47+
./scripts/install_full.sh
48+
49+
# Style checking (fast, ~30 seconds)
50+
azdev style
51+
52+
# Comprehensive linting (medium speed, 2-3 minutes)
53+
azdev linter --ci-exclusions --min-severity medium
54+
55+
# Quick linter for specific changes
56+
azdev linter --ci-exclusions --min-severity medium --repo ./ --src HEAD --tgt origin/dev
57+
58+
# Check command coverage for a module
59+
azdev cmdcov {module_name}
60+
azdev cmdcov {module_name} --level argument # argument-level coverage
61+
```
62+
63+
### Testing Commands
64+
```bash
65+
# Run tests for specific module (recommended for development)
66+
azdev test {module_name}
67+
68+
# Run tests with verbose output and timing
69+
azdev test {module_name} --verbose --pytest-args "--durations=10"
70+
71+
# Run tests in serial mode (for modules like appservice, botservice, cloud, network)
72+
azdev test --series {module_name}
73+
74+
# Full test suite (WARNING: very time-consuming, 30+ minutes)
75+
azdev test --profile latest
76+
77+
# Quick self-test to verify CLI functionality
78+
az self-test
79+
```
80+
81+
### Package Building
82+
```bash
83+
# Build Python wheels
84+
./scripts/release/pypi/build.sh
85+
86+
# Build for specific platforms (Windows)
87+
build_scripts/windows/scripts/build.cmd
88+
89+
# Install and test from packages
90+
pip install --find-links ./dist azure-cli
91+
```
92+
93+
## Project Layout and Architecture
94+
95+
### Core Module Structure
96+
```
97+
src/
98+
├── azure-cli/ # Main CLI package
99+
├── azure-cli-core/ # Core functionality and framework
100+
├── azure-cli-telemetry/ # Telemetry collection
101+
└── azure-cli-testsdk/ # Testing framework and utilities
102+
```
103+
104+
### Key Directories
105+
- `scripts/`: Build and utility scripts (install_full.sh, CI scripts)
106+
- `build_scripts/`: Platform-specific build scripts (Windows, RPM, DEB)
107+
- `doc/`: Development documentation and authoring guides
108+
- `.azure-pipelines/`: Azure DevOps CI/CD configuration
109+
- `.github/`: GitHub Actions and policies
110+
111+
### Configuration Files
112+
- `.flake8`: Style checking configuration (max-line-length: 120)
113+
- `pylintrc`: Linting rules and exclusions
114+
- `linter_exclusions.yml`: Module-specific linter exemptions
115+
- `requirements.txt`: Basic dependencies (setuptools, pip)
116+
- `nose.cfg`: Test runner configuration
117+
118+
## Validation Pipeline
119+
120+
### Pre-commit Checks
121+
The repository enforces several checks before code integration:
122+
1. **Pull Request Format**: Title and content validation
123+
2. **Style Check**: `azdev style` (enforced via GitHub Actions)
124+
3. **Linting**: `azdev linter --ci-exclusions --min-severity medium`
125+
4. **Unit Tests**: Module-specific test suites
126+
5. **Command Coverage**: Ensure all commands have tests
127+
6. **Secret Scanning**: `azdev scan` for credential detection
128+
129+
### CI/CD Pipeline Structure
130+
- **Azure DevOps**: Primary build system with multi-platform matrix
131+
- **GitHub Actions**: Style and linting validation for PRs
132+
- **Package Validation**: MSI, DEB, RPM, Docker, Homebrew testing
133+
- **Live Testing**: Nightly runs against actual Azure services
134+
135+
### Build Timing Expectations
136+
- Style check: ~30 seconds
137+
- Linting: 2-3 minutes
138+
- Module tests: 5-15 minutes per module
139+
- Full test suite: 30+ minutes
140+
- Package builds: 10-20 minutes per platform
141+
142+
## Common Patterns and Conventions
143+
144+
### Command Module Development
145+
- Each command module lives in `src/azure-cli/azure/cli/command_modules/`
146+
- Use `azdev cmdcov` to ensure 100% command coverage
147+
- Follow naming: `test_<module>_<feature>` for test methods
148+
- Always include tests for new commands (PRs rejected without tests)
149+
150+
### Testing Best Practices
151+
- Use `ScenarioTest` for integration tests with VCR.py recording
152+
- Serial modules: `appservice`, `botservice`, `cloud`, `network`, `azure-cli-core`, `azure-cli-telemetry`
153+
- 100% command coverage required (use `azdev cmdcov` to verify)
154+
- Test boundary values: empty strings, null, 0, False
155+
156+
### Code Quality Standards
157+
- Maximum line length: 120 characters
158+
- Follow existing linter exclusions in `linter_exclusions.yml`
159+
- Use `azdev style` before committing
160+
- Address linter warnings with `--min-severity medium`
161+
162+
## Troubleshooting Common Issues
163+
164+
### Network/Installation Issues
165+
- Pip timeouts: Use `pip install --timeout 300 --retries 10`
166+
- Dependency conflicts: Create fresh virtual environment
167+
- azdev setup failures: Ensure virtual environment is activated
168+
169+
### Build Issues
170+
- Windows: Ensure proper Visual Studio components installed
171+
- macOS: May need to relink Python in Homebrew
172+
- Linux: Check for required development packages
173+
174+
### Test Issues
175+
- Live test failures: Check Azure service availability
176+
- Recording issues: Ensure proper test isolation
177+
- Coverage issues: Use `azdev cmdcov` to identify gaps
178+
179+
## Important Notes for Agents
180+
181+
1. **ALWAYS use azdev**: Never use the deprecated `dev_setup.py` script
182+
2. **Virtual environment required**: All development must be in a virtual environment
183+
3. **Trust these instructions**: Only search for additional information if these instructions are incomplete or incorrect
184+
4. **Style before commit**: Always run `azdev style` before making changes
185+
5. **Test coverage mandatory**: All new commands require tests
186+
6. **Incremental testing**: Use module-specific tests during development, not full suite
187+
7. **Network resilience**: Be prepared for pip timeout issues and retry with longer timeouts
188+
189+
This repository has complex build requirements but following these instructions will minimize exploration time and avoid common pitfalls. The development workflow is well-established through azdev tooling.

0 commit comments

Comments
 (0)