From 04c5d30c2357bb65dba8e1c35bba42f25f865ece Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 Aug 2025 14:56:16 +0000 Subject: [PATCH 1/3] Initial plan From 4fbdb6e5d84676d0bebaff4fbc10a950e4be3ec1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 Aug 2025 15:11:59 +0000 Subject: [PATCH 2/3] Create comprehensive .github/copilot-instructions.md for Azure CLI development Co-authored-by: zhoxing-ms <16612065+zhoxing-ms@users.noreply.github.com> --- .github/copilot-instructions.md | 189 ++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..bda2601e02c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,189 @@ +# Azure CLI Copilot Development Instructions + +## Repository Overview + +**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. + +- **Primary Language**: Python 3.9-3.12 (3.12 recommended) +- **Repository Type**: Command-line interface with command modules +- **Target Platforms**: Windows, Linux, macOS +- **Package Formats**: MSI, DEB, RPM, Docker, Homebrew, PyPI wheels +- **Development Tool**: `azdev` (Azure Developer Tool) - **DO NOT use the deprecated `dev_setup.py`** + +## Essential Development Setup + +### Prerequisites +- Python 3.9-3.12 (3.12 preferred) +- Git +- Virtual environment support + +### Quick Start (ALWAYS follow this order) +```bash +# 1. Create and activate virtual environment +python -m venv env +source env/bin/activate # Linux/Mac +# env\Scripts\activate # Windows + +# 2. Upgrade pip first +python -m pip install --upgrade pip + +# 3. Install azdev (may take 2-3 minutes) +pip install azdev + +# 4. Setup development environment (may take 5-10 minutes) +azdev setup -c + +# 5. Verify installation +az --version +``` + +**Network Issues**: If pip install fails with timeout errors, retry with `--timeout 300` or `--retries 10`. This is common in this repository. + +## Build and Validation Commands + +### Core Development Commands +```bash +# Install all modules from source (alternative to azdev setup) +./scripts/install_full.sh + +# Style checking (fast, ~30 seconds) +azdev style + +# Comprehensive linting (medium speed, 2-3 minutes) +azdev linter --ci-exclusions --min-severity medium + +# Quick linter for specific changes +azdev linter --ci-exclusions --min-severity medium --repo ./ --src HEAD --tgt origin/dev + +# Check command coverage for a module +azdev cmdcov {module_name} +azdev cmdcov {module_name} --level argument # argument-level coverage +``` + +### Testing Commands +```bash +# Run tests for specific module (recommended for development) +azdev test {module_name} + +# Run tests with verbose output and timing +azdev test {module_name} --verbose --pytest-args "--durations=10" + +# Run tests in serial mode (for modules like appservice, botservice, cloud, network) +azdev test --series {module_name} + +# Full test suite (WARNING: very time-consuming, 30+ minutes) +azdev test --profile latest + +# Quick self-test to verify CLI functionality +az self-test +``` + +### Package Building +```bash +# Build Python wheels +./scripts/release/pypi/build.sh + +# Build for specific platforms (Windows) +build_scripts/windows/scripts/build.cmd + +# Install and test from packages +pip install --find-links ./dist azure-cli +``` + +## Project Layout and Architecture + +### Core Module Structure +``` +src/ +├── azure-cli/ # Main CLI package +├── azure-cli-core/ # Core functionality and framework +├── azure-cli-telemetry/ # Telemetry collection +└── azure-cli-testsdk/ # Testing framework and utilities +``` + +### Key Directories +- `scripts/`: Build and utility scripts (install_full.sh, CI scripts) +- `build_scripts/`: Platform-specific build scripts (Windows, RPM, DEB) +- `doc/`: Development documentation and authoring guides +- `.azure-pipelines/`: Azure DevOps CI/CD configuration +- `.github/`: GitHub Actions and policies + +### Configuration Files +- `.flake8`: Style checking configuration (max-line-length: 120) +- `pylintrc`: Linting rules and exclusions +- `linter_exclusions.yml`: Module-specific linter exemptions +- `requirements.txt`: Basic dependencies (setuptools, pip) +- `nose.cfg`: Test runner configuration + +## Validation Pipeline + +### Pre-commit Checks +The repository enforces several checks before code integration: +1. **Pull Request Format**: Title and content validation +2. **Style Check**: `azdev style` (enforced via GitHub Actions) +3. **Linting**: `azdev linter --ci-exclusions --min-severity medium` +4. **Unit Tests**: Module-specific test suites +5. **Command Coverage**: Ensure all commands have tests +6. **Secret Scanning**: `azdev scan` for credential detection + +### CI/CD Pipeline Structure +- **Azure DevOps**: Primary build system with multi-platform matrix +- **GitHub Actions**: Style and linting validation for PRs +- **Package Validation**: MSI, DEB, RPM, Docker, Homebrew testing +- **Live Testing**: Nightly runs against actual Azure services + +### Build Timing Expectations +- Style check: ~30 seconds +- Linting: 2-3 minutes +- Module tests: 5-15 minutes per module +- Full test suite: 30+ minutes +- Package builds: 10-20 minutes per platform + +## Common Patterns and Conventions + +### Command Module Development +- Each command module lives in `src/azure-cli/azure/cli/command_modules/` +- Use `azdev cmdcov` to ensure 100% command coverage +- Follow naming: `test__` for test methods +- Always include tests for new commands (PRs rejected without tests) + +### Testing Best Practices +- Use `ScenarioTest` for integration tests with VCR.py recording +- Serial modules: `appservice`, `botservice`, `cloud`, `network`, `azure-cli-core`, `azure-cli-telemetry` +- 100% command coverage required (use `azdev cmdcov` to verify) +- Test boundary values: empty strings, null, 0, False + +### Code Quality Standards +- Maximum line length: 120 characters +- Follow existing linter exclusions in `linter_exclusions.yml` +- Use `azdev style` before committing +- Address linter warnings with `--min-severity medium` + +## Troubleshooting Common Issues + +### Network/Installation Issues +- Pip timeouts: Use `pip install --timeout 300 --retries 10` +- Dependency conflicts: Create fresh virtual environment +- azdev setup failures: Ensure virtual environment is activated + +### Build Issues +- Windows: Ensure proper Visual Studio components installed +- macOS: May need to relink Python in Homebrew +- Linux: Check for required development packages + +### Test Issues +- Live test failures: Check Azure service availability +- Recording issues: Ensure proper test isolation +- Coverage issues: Use `azdev cmdcov` to identify gaps + +## Important Notes for Agents + +1. **ALWAYS use azdev**: Never use the deprecated `dev_setup.py` script +2. **Virtual environment required**: All development must be in a virtual environment +3. **Trust these instructions**: Only search for additional information if these instructions are incomplete or incorrect +4. **Style before commit**: Always run `azdev style` before making changes +5. **Test coverage mandatory**: All new commands require tests +6. **Incremental testing**: Use module-specific tests during development, not full suite +7. **Network resilience**: Be prepared for pip timeout issues and retry with longer timeouts + +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. \ No newline at end of file From 8295e91f519ae392010ab8f8b7c53bcba862c98b Mon Sep 17 00:00:00 2001 From: Xing Zhou Date: Tue, 12 Aug 2025 23:35:46 +0800 Subject: [PATCH 3/3] Update copilot-instructions.md --- .github/copilot-instructions.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bda2601e02c..b49ec8f7541 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -176,6 +176,37 @@ The repository enforces several checks before code integration: - Recording issues: Ensure proper test isolation - Coverage issues: Use `azdev cmdcov` to identify gaps +## Specific Coding Guidelines for PR review + +### 1. Rule of help messages +--- +applyTo: "src/azure-cli/azure/cli/command_modules/**/_params.py" +--- +Firstly, find the help messages, their format is `...help='{help_message}'...` or `....help="{help_message}"...`, {help_message} is the placeholder +Next, you need to review the format of the found help messages according to the following rules: +1. If the help message does not start with a verb, skip this check. Otherwise, check the verb at the beginning of help message +2. Confirm if the verb is in the first person voice, such as the third person voice of 'Enables......' is not compliant +3. Confirm if the verb is in the active voice, such as the passive voice 'Enabled......' is not compliant + +### 2. Confirmation for dangerous commands +--- +applyTo: "src/azure-cli/azure/cli/command_modules/**/commands.py" +--- +Firstly, find the command signature, their format is `... g.custom_command('{command_signature}', ...)...` or `... g.command('{command_signature}', ...)...`, {command_signature} is the command signature +Next, you need to determine whether the command signature is a dangerous operation, such as `delete`, `remove`, `stop` operation which will break or remove resources. If so, You need to suggest adding the flag `confirmation=True`, such as `g.custom_command('{command_signature}', ..., )...` + +### 3. Common code best practices +- ​​Use 4 spaces for indentation​​, never mix tabs and spaces +​​- Naming: + (1) Variables/functions: snake_case + (2) Classes: CamelCase + (3) Constants: UPPER_CASE_WITH_UNDERSCORES +- ​​Surround operators with spaces​​ (x = y + 1), except in function parameters +- ​​Avoid extraneous whitespace​​ in brackets, before commas/colons +- ​​Handle exceptions explicitly​​ using try-except blocks +- ​​Break long expressions​​ using parentheses alignment or hanging indents +​​- Use blank lines​​: two between top-level definitions, one between methods + ## Important Notes for Agents 1. **ALWAYS use azdev**: Never use the deprecated `dev_setup.py` script @@ -186,4 +217,4 @@ The repository enforces several checks before code integration: 6. **Incremental testing**: Use module-specific tests during development, not full suite 7. **Network resilience**: Be prepared for pip timeout issues and retry with longer timeouts -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. \ No newline at end of file +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.