diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 556b59337ecb..88010f47d678 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,169 +1,11 @@ -# AZURE SDK FOR PYTHON - COPILOT INSTRUCTIONS +# Repository guidance has moved -> **Note**: For general AI agent guidelines and repository overview, see [AGENTS.md](https://github.com/Azure/azure-sdk-for-python/blob/main/AGENTS.md) at the repository root. +Agent-facing guidance for this repository lives in +[`AGENTS.md`](../AGENTS.md) at the repository root. ---- +`AGENTS.md` is a resolver that points to canonical task skills, path-scoped +reviewer instructions, package-specific skills, and contributor documentation. +Start there rather than duplicating guidance in this file. -## CORE PRINCIPLES - -### RULE 1: DO NOT REPEAT INSTRUCTIONS -**NEVER repeat instructions when guiding users. Users should follow instructions independently.** - -### RULE 2: REFERENCE OFFICIAL DOCUMENTATION -**ALWAYS** reference the [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html) -- Link to specific pages when answering guidelines questions -- Use this as the authoritative source for SDK development guidance - -### RULE 3: VERIFY ENVIRONMENT FIRST -**REQUIRED CONDITIONS:** -- To use Azure MCP tool calls, users must have PowerShell installed. Provide [PowerShell installation instructions](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) if not installed, and recommend restarting the IDE to start the MCP server. -- When using Copilot from Visual Studio or VS Code (not applicable when using Coding Agent on Github.com): - - **Always run** the [`azsdk_verify_setup`](../eng/common/instructions/azsdk-tools/verify-setup.instructions.md) tool first to validate the user's development environment for SDK MCP tools. - - **Do not proceed** with any other tool execution until this step is complete. - - **Skip this check only** for queries that do not require tool execution. - ---- - -## PYLINT OPERATIONS - -### RUNNING PYLINT - -**REFERENCE DOCUMENTATION:** -- [Official pylint guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md) -- [Tool usage guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md) - -**COMMAND:** -```bash -azpysdk pylint . -``` - -### FIXING PYLINT WARNINGS - -**REFERENCE SOURCES:** -- [Azure pylint guidelines](https://github.com/Azure/azure-sdk-tools/blob/main/tools/pylint-extensions/azure-pylint-guidelines-checker/README.md) -- [Pylint documentation](https://pylint.readthedocs.io/en/stable/user_guide/checkers/features.html) - -**ALLOWED ACTIONS:** -✅ Fix warnings with 100% confidence -✅ Use existing file for all solutions -✅ Reference official guidelines - -**FORBIDDEN ACTIONS:** -❌ Fix warnings without complete confidence -❌ Create new files for solutions -❌ Import non-existent modules -❌ Add new dependencies/imports -❌ Make unnecessary large changes -❌ Change code style without reason -❌ Delete code without clear justification - ---- - -## MYPY OPERATIONS - -### RUNNING AND FIXING MYPY - -**REFERENCE DOCUMENTATION:** -- [Tool usage guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md) -- [MyPy fixing guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md) - -**REQUIREMENTS:** -- Use Python 3.10 compatible environment -- Follow official fixing guidelines -- Run `azpysdk mypy .` from the package directory - ---- - -## Python SDK Health tool - -- Use the azure-sdk-python-mcp mcp tool to lookup a library's health status. -- Always include the date of last update based on the Last Refresh date. -- Explanation of statuses can be found here: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/repo_health_status.md -- Release blocking checks are MyPy, Pylint, Sphinx, and Tests - CI. These checks should all PASS. If not PASS, mention that the library is blocked for release. -- If links are available in the table, make the statuses (e.g. PASS, WARNING, etc) you report linked. Avoid telling the user to check the links in the report themselves. -- Don't share information like SDK Owned - -### Example - -As of , here is the health status for azure-ai-projects: - -Overall Status: ⚠️ NEEDS_ACTION - -✅ Passing Checks: - -Pyright: PASS -Sphinx: PASS -Type Checked Samples: ENABLED -SLA Questions and Bugs: 0 - -⚠️ Areas Needing Attention: - -Pylint: WARNING -Tests - Live: ❓ UNKNOWN -Tests - Samples: ❌ DISABLED -Customer-reported issues: 🔴 5 open issues - -❌ Release blocking - -Mypy: FAIL -Tests - CI: FAIL - -This library is failing two release blocking checks - Mypy and Tests - CI. The library needs attention primarily due to Pylint warnings, disabled sample tests, and open customer-reported issues. - ---- - -## Local SDK Generation and Package Lifecycle (TypeSpec) - -### AUTHORITATIVE REFERENCE -For all TypeSpec-based SDK workflows (generation, building, validation, testing, versioning, and release), follow #file:skills/azsdk-common-generate-sdk-locally/SKILL.md - -### DEFAULT BEHAVIORS -- **Repository:** Use the current workspace as the local SDK repository unless the user specifies a different path. -- **Configuration:** Identify `tsp-location.yaml` from files open in the editor. If unclear, ask the user. - -### PYTHON-SPECIFIC RULES -- **Skip build step:** Python packages do not require compilation. After generation, proceed directly to validation and tests. - -### REQUIRED CONFIRMATIONS -Ask the user for clarification if repository path or configuration file is ambiguous. - ---- - -## MGMT SDK Code Review Rules - -### SCOPE -These rules apply to management-plane SDK packages located at `sdk/*/azure-mgmt-*/`. - -### REVIEW EXCLUSIONS -- **Skip** the `generated_samples/` and `generated_tests/` folders entirely — do not review generated sample or test code. -- **Skip** source code under `azure/mgmt/**/` **except** `_client.py` — only review `_client.py` among the generated source files. - -### VERSION CONSISTENCY -- The version string in `_version.py` **must** match the latest version listed in `CHANGELOG.md`. - -### CHANGELOG DATE -- If the release date of the latest version in `CHANGELOG.md` is **more than 3 weeks in the future** from the current date, remind the author to verify and update the date. - -### PYPROJECT.TOML STABILITY FLAGS -- **Stable version** (version string does **not** contain `b`): - - `is_stable` in `pyproject.toml` must be `true` - - `classifiers` must include `"Development Status :: 5 - Production/Stable"` -- **Preview version** (version string contains `b`): - - `is_stable` in `pyproject.toml` must be `false` - - `classifiers` must include `"Development Status :: 4 - Beta"` - -### CLIENT SIGNATURE -- The `__init__` method of the client class in `_client.py` must include the parameters `credential`, `subscription_id`, and `base_url` **in that order**. Default values are not checked. -- If `subscription_id` is **not** present in the client's `__init__` signature, `pyproject.toml` must contain `no_sub = true`. If it does not, hint the user to add `no_sub = true` in `pyproject.toml` and regenerate the SDK. - -### CLIENT NAME CONSISTENCY -- The client class name in `_client.py`, the client name referenced in `README.md`, and the `title` value in `pyproject.toml` must all be the same. - -### README CODE SNIPPETS -- Code snippets in `README.md` must follow the real client class signatures and usage patterns. Verify that sample code matches the actual client API. - ---- - -## SDK release - -For detailed workflow instructions, see [SDK Release](skills/azsdk-common-sdk-release/SKILL.md). +This lightweight redirect remains for tools that discover +`.github/copilot-instructions.md` by its conventional path. diff --git a/.github/instructions/reviewer/mgmt-sdk.instructions.md b/.github/instructions/reviewer/mgmt-sdk.instructions.md new file mode 100644 index 000000000000..3880df16a985 --- /dev/null +++ b/.github/instructions/reviewer/mgmt-sdk.instructions.md @@ -0,0 +1,51 @@ +--- +applyTo: "sdk/*/azure-mgmt-*/**" +description: "Azure management-plane SDK review rules for generated source, versions, metadata, and client documentation." +--- + +# Management SDK review rules + +Apply these rules only to management-plane packages under +`sdk/*/azure-mgmt-*/`. Only report issues introduced by the change under +review. + +## Review scope + +- Skip `generated_samples/` and `generated_tests/`. +- Skip generated source under `azure/mgmt/**/` except `_client.py`. +- Review package metadata, `CHANGELOG.md`, `README.md`, and the public client + signature where relevant. + +## Version consistency + +- The version in `_version.py` must match the latest version in `CHANGELOG.md`. +- If `_metadata.json` has an `apiVersion` containing `preview`, `_version.py` + must contain a preview version such as `1.0.0b1`, not a stable version such + as `1.0.0`. +- If the latest `CHANGELOG.md` release date is more than three weeks in the + future, ask the author to verify the date. + +## Package stability metadata + +For a stable version, whose version string does not contain `b`: + +- `pyproject.toml` must set `is_stable = true`. +- Classifiers must include + `"Development Status :: 5 - Production/Stable"`. + +For a preview version, whose version string contains `b`: + +- `pyproject.toml` must set `is_stable = false`. +- Classifiers must include `"Development Status :: 4 - Beta"`. + +## Client consistency + +- The client `__init__` signature in `_client.py` must contain `credential`, + `subscription_id`, and `base_url` in that order. Default values are not part + of this check. +- If `subscription_id` is absent, `pyproject.toml` must contain + `no_sub = true`. Otherwise, recommend adding it and regenerating the SDK. +- The client class name in `_client.py`, the client name used in `README.md`, + and the `title` in `pyproject.toml` must match. +- README code snippets must follow the actual client signature and usage + pattern. diff --git a/.github/prompts/check-package-health.prompt.md b/.github/prompts/check-package-health.prompt.md new file mode 100644 index 000000000000..666870710125 --- /dev/null +++ b/.github/prompts/check-package-health.prompt.md @@ -0,0 +1,18 @@ +--- +mode: "agent" +description: "Report the Azure SDK for Python health status of a package." +--- + +# Check package health + +Use the available Azure SDK Python package-health tool to retrieve the package +health report. + +- Include the report's **Last Refresh** date. +- Interpret statuses according to + [`doc/repo_health_status.md`](../../doc/repo_health_status.md). +- Treat MyPy, Pylint, Sphinx, and Tests - CI as release-blocking checks. State + clearly when any of them is not passing and the package is blocked. +- Link reported statuses when the health report provides links. +- Do not expose internal ownership fields such as `SDK Owned`. +- Separate passing checks, areas needing attention, and release blockers. diff --git a/.github/prompts/check-package-readiness.prompt.md b/.github/prompts/check-package-readiness.prompt.md index cd30574baa12..74106db8e5a1 100644 --- a/.github/prompts/check-package-readiness.prompt.md +++ b/.github/prompts/check-package-readiness.prompt.md @@ -1,10 +1,10 @@ --- mode: 'agent' -tools: ['CheckPackageReleaseReadiness'] -description: 'This prompt is designed to check the release readiness of a SDK package.' +description: 'Check the release readiness of an SDK package.' --- ## Goal -Check the release readiness of an SDK package by collecting the required information from the user and executing the readiness check. +Check the release readiness of an SDK package using the +`azsdk-common-sdk-release` skill. ## Instructions 1. **Collect Required Information**: @@ -17,7 +17,8 @@ Check the release readiness of an SDK package by collecting the required informa - Go 2. **Execute Readiness Check**: - - Use the `CheckPackageReleaseReadiness` tool with the provided package name and selected language + - Follow `.github/skills/azsdk-common-sdk-release/SKILL.md`. + - Use `azure-sdk-mcp:azsdk_release_sdk` with `checkReady: true`. - Do not check for existing pull requests to run this step. - Do not ask the user to create a release plan to run this step. diff --git a/.github/skills/create-package-skill/SKILL.md b/.github/skills/create-package-skill/SKILL.md index a19ee8e421de..93cf69ba5070 100644 --- a/.github/skills/create-package-skill/SKILL.md +++ b/.github/skills/create-package-skill/SKILL.md @@ -41,7 +41,8 @@ Run each phase in order. **Progressive loading:** Read only the current phase fi - Every line must be non-obvious and package-specific. No generic Python/SDK boilerplate. - SKILL.md should be under 500 tokens (soft limit). Move details to references/. - References under 1000 tokens each. Split if larger. -- Never duplicate what's already in `.github/copilot-instructions.md` or shared skills. +- Never duplicate what's already in `AGENTS.md`, shared skills, or path-scoped + reviewer instructions. **Relationship to existing SDK tools:** - Package skills **complement** the Azure SDK MCP tools (`azsdk_package_generate_code`, `azsdk_package_build_code`, `azsdk_customized_code_update`, etc.) — they do NOT replace them. diff --git a/.github/skills/create-package-skill/phases/00-scan-package.md b/.github/skills/create-package-skill/phases/00-scan-package.md index f3ca568d502b..4e97be5f959f 100644 --- a/.github/skills/create-package-skill/phases/00-scan-package.md +++ b/.github/skills/create-package-skill/phases/00-scan-package.md @@ -55,7 +55,10 @@ Scan the package using the checklist below. Use file_search / grep_search / read 12. **Documentation surfaces**: Check for `CHANGELOG.md` and `README.md` at the package root. Both are near-universal; the skill's Step 7 (Update Documentation and Samples) will reference them. -13. **Management vs data plane**: If package name starts with `azure-mgmt-` → management-plane rules apply (see copilot-instructions). Otherwise data-plane. +13. **Management vs data plane**: If package name starts with `azure-mgmt-` → + management-plane rules apply (see + `.github/instructions/reviewer/mgmt-sdk.instructions.md`). Otherwise + data-plane. ## Step 3 — Present Package Profile diff --git a/AGENTS.md b/AGENTS.md index c429ffec5819..ba7d0dafc564 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,320 +1,82 @@ -# AGENTS.md - Azure SDK for Python - -This file describes how AI agents (e.g., GitHub Copilot, MCP servers, or LLM-based assistants) should interact with this repository. - -## Repository Overview - -**Purpose**: This repository contains the active development of the Azure SDK for Python, providing client libraries and management libraries for Azure services. - -**Scope**: -- 100+ Python packages for Azure services -- Client libraries for data plane operations -- Management libraries for Azure Resource Manager (ARM) -- Shared core functionality (authentication, retries, logging, transport) -- TypeSpec-based SDK generation from API specifications -- Comprehensive testing, validation, and documentation infrastructure - -**Main Branch**: `main` - -**Key Documentation**: -- [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html) -- [Contributing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md) -- [Developer Documentation](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev) - -## Repository Structure - -``` -azure-sdk-for-python/ -├── sdk/ # Service-specific libraries (e.g., sdk/storage/, sdk/ai/) -├── eng/ # Engineering system tools and configurations -├── doc/ # Developer documentation and guides -├── scripts/ # Automation scripts -├── .github/ # GitHub workflows, Copilot instructions, skills, and prompts -│ ├── copilot-instructions.md # Detailed Copilot-specific guidance -│ ├── skills/ # Reusable Copilot skills (e.g., find-package, fix-pylint) -│ └── prompts/ # Copilot prompt files for common tasks -└── tools/ # Development tools -``` - -## AI Agent Guidelines - -### Supported Actions - -AI agents can assist with the following activities: - -#### Code Generation & Development -- **TypeSpec SDK Generation**: Generate Python SDKs from TypeSpec specifications - - Follow the complete workflow in `.github/copilot-instructions.md` - - Use MCP tools for environment verification, code generation, and validation - - Time estimate: 10-15 minutes for full generation workflow - -- **Code Fixes**: Address linting, type checking, and validation issues - - Pylint, MyPy, Pyright, Verifytypes, Sphinx warnings - - Follow official guidelines and existing patterns - - Make minimal, surgical changes - -- **Documentation**: Update CHANGELOG.md, README files, and API documentation - - Follow existing formatting conventions - - Include version information and release dates - -#### Testing & Validation -- **Run Tests**: Execute test suites using the `azpysdk` test runner - - Unit tests, integration tests, samples - - Support both local and CI environments - -- **Static Analysis**: Run and fix issues from: - - Pylint (code quality) - - MyPy, Pyright (type checking) - - Bandit (security) - - Black (formatting) - - Sphinx (documentation) - -#### Pull Request Management -- **PR Creation**: Create draft PRs with descriptive titles and descriptions -- **PR Review**: Analyze PR feedback and make requested changes -- **Status Checks**: Monitor CI/CD pipeline status and address failures - -#### Issue Triage & Labeling -- **Issue Analysis**: Review and categorize issues -- **Service Labels**: Validate and create service labels (e.g., `Azure.AI.Projects`) -- **CODEOWNERS**: Validate and update CODEOWNERS entries - -### Relationship to Copilot Instructions - -This `AGENTS.md` file is the primary reference for AI agents working in this repository. It follows the [AGENTS.md standard](https://github.com/agentsmd/agents.md) that most AI coding tools recognize automatically. For additional Copilot-specific guidance (e.g., TypeSpec generation details, MCP tool usage), see [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md). Reusable skills are available in [`.github/skills/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/) and prompt templates in [`.github/prompts/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/prompts/). - -### Key Workflows - -#### 1. TypeSpec SDK Generation Workflow - -**Prerequisites**: -- GitHub CLI authenticated (`gh auth login`) -- Feature branch (not `main`) -- PowerShell installed (for MCP tools) -- Python virtual environment active - -**Steps**: -1. **Environment Verification** - Use `verify_setup` MCP tool -2. **SDK Generation** - Use azure-sdk-python-mcp generation tools (~2 minutes) -3. **Static Validation** - Run sequential validation steps (~3-5 minutes each): - - Pylint, MyPy, Pyright, Verifytypes - - Sphinx, Mindependency, Bandit, Black - - Samples, Breaking changes -4. **Documentation Update** - Update CHANGELOG.md and version files -5. **Commit & Push** - Stage, commit, and push changes -6. **PR Creation** - Create draft PR with generated description -7. **Handoff** - Provide PR link for azure-rest-api-specs agent - -**Estimated Time**: 10-15 minutes - -#### 2. Code Quality Workflow - -**Running Validation**: -```bash -# Use azpysdk with appropriate environment from the package directory -azpysdk . - -# Examples: -azpysdk pylint . -azpysdk mypy . -``` - -**Fixing Issues**: -- Reference official guidelines: - - [Pylint Guidelines](https://github.com/Azure/azure-sdk-tools/blob/main/tools/pylint-extensions/azure-pylint-guidelines-checker/README.md) - - [MyPy Type Checking Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md) - - [azpysdk Test Runner Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md) -- Make minimal changes that address specific warnings -- Avoid adding new dependencies or large refactoring -- Rerun validation after each fix - -#### 3. SDK Release Workflow - -**Check Release Readiness**: -- Use `CheckPackageReleaseReadiness` MCP tool -- Validates: API review status, changelog, package approval, release date - -**Release Package**: -- Use `ReleasePackage` MCP tool -- Triggers release pipeline (requires approval) - -**Release Blocking Checks**: -- MyPy: PASS -- Pylint: PASS -- Sphinx: PASS -- Tests - CI: PASS - -### Automation Boundaries - -#### Safe Operations -✅ Generate SDK code from TypeSpec specifications -✅ Run linting and static analysis tools -✅ Fix code quality warnings (with high confidence) -✅ Update documentation (CHANGELOG, README) -✅ Create and update PRs in draft mode -✅ Run existing test suites -✅ Validate CODEOWNERS entries - -#### Restricted Operations -⚠️ Modifying generated code (requires review) -⚠️ Adding new dependencies (requires justification) -⚠️ Changing API signatures (requires design review) -⚠️ Disabling or removing tests (requires explanation) -⚠️ Large-scale refactoring (requires approval) - -#### Prohibited Operations -❌ Merging PRs without human review -❌ Releasing packages to PyPI -❌ Modifying CI/CD pipeline definitions -❌ Changing security or authentication logic without security review -❌ Committing secrets or credentials -❌ Force pushing to protected branches - -### Environment Requirements - -**Required Tools**: -- Python 3.10 or later -- Node.js (for TypeSpec generation) -- azpysdk (test runner and automation) -- GitHub CLI (for PR operations) -- PowerShell (for MCP server on Windows) - -**MCP Server Tools**: -- `azure-sdk-python-mcp` - Python-specific SDK operations -- `azure-sdk-mcp` - Cross-language SDK operations -- `azsdk-tools` - Engineering system utilities - -**Virtual Environment**: -```bash -# Create and activate virtual environment -python -m venv .venv -source .venv/bin/activate # Linux/macOS -.venv\Scripts\activate # Windows -``` - -### CI/CD Integration - -**Pipeline System**: Azure DevOps - -**Key Pipelines**: -- **Python CI**: Core library tests and validation -- **SDK Generation**: TypeSpec-based code generation -- **Release**: Package publication to PyPI - -**Status Monitoring**: -- Use `get_pipeline_status` MCP tool -- Check build logs for failures -- Analyze failed tests with `get_failed_test_cases` tool - -**Artifact Analysis**: -- Download artifacts with `get_pipeline_llm_artifacts` -- Review TRX test results -- Analyze log files with `analyze_log_file` tool - -### SDK-Specific Conventions - -#### Package Naming -- Client libraries: `azure--` (e.g., `azure-storage-blob`) -- Management libraries: `azure-mgmt-` (e.g., `azure-mgmt-compute`) - -#### Version Conventions -- Semantic versioning: `MAJOR.MINOR.PATCH` -- Preview versions: `MAJOR.MINOR.PATCHbN` (e.g., `1.0.0b1`) -- Pre-release format in CHANGELOG: `## 1.0.0b1 (YYYY-MM-DD)` - -#### Code Style -- Follow [PEP 8](https://peps.python.org/pep-0008/) -- Use Black for formatting -- Type hints required (PEP 484) -- Docstrings in NumPy/Google style - -#### Testing -- Use pytest framework -- Separate live and recorded tests -- Test recordings in `tests/recordings/` -- Environment variables for credentials (never hardcode) - -## Cross-References - -**Detailed Copilot Instructions**: See [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md) for: -- Complete TypeSpec SDK generation workflow -- Detailed validation steps and commands -- Pylint and MyPy fixing guidelines -- SDK health status interpretation -- SDK release procedures - -**Developer Documentation**: See [doc/dev/](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev) for: -- [TypeSpec Generation Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md) -- [Testing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md) -- [Test Runner (azpysdk)](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md) -- [Pylint Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md) -- [Type Checking Cheat Sheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md) - -## Example Prompts - -### SDK Generation -``` -"Generate a Python SDK using TypeSpec from tspconfig.yaml at " -"Start TypeSpec SDK generation workflow" -"Generate SDK from my local TypeSpec project at sdk/cognitiveservices/azure-ai-projects" -``` - -### Validation & Fixes -``` -"Run pylint validation and fix any warnings" -"Check if my SDK passes all static validation steps" -"Fix the mypy errors in the generated SDK" -``` - -### Release Management -``` -"Check if azure-ai-projects is ready for release" -"What is the health status of azure-storage-blob?" -"Release azure-ai-inference version 1.0.0" -``` - -### Repository Health -``` -"Show me the health status for azure-ai-projects" -"Which checks are blocking the release of this library?" -"Are there any open customer issues for this package?" -``` - -## Agent Behavior Guidelines - -### Best Practices -1. **Always verify environment first** - Run `verify_setup` before SDK operations -2. **Inform users of time expectations** - SDK generation takes 10-15 minutes -3. **Make minimal changes** - Only modify files with validation errors -4. **Reference official documentation** - Link to Azure SDK design guidelines -5. **Run validation iteratively** - Fix and rerun each step before proceeding -6. **Use MCP tools when available** - Leverage specialized SDK tooling -7. **Create draft PRs** - Never create PRs in ready-for-review state -8. **Report progress frequently** - Use incremental commits - -### Error Handling -- For TypeSpec errors: Direct users to fix in source repository -- For authentication failures: Guide through `gh auth login` -- For missing dependencies: Provide installation instructions with links -- For validation failures: Reference specific fixing guidelines -- For pipeline failures: Analyze logs and provide actionable feedback - -### Communication Style -- Don't repeat instructions - reference documentation links -- Be concise and actionable -- Use markdown formatting for commands and code -- Provide time estimates for long operations -- Highlight release-blocking issues clearly - -## Reporting Issues - -To report issues with AI agent interactions or suggest improvements: -- **GitHub Issues**: [Azure SDK for Python Issues](https://github.com/Azure/azure-sdk-for-python/issues) -- **Label**: Use `Agent` label for agent-related issues -- **Include**: Agent name/version, prompt used, expected vs actual behavior - -## Version - -**AGENTS.md Version**: 1.0.0 -**Last Updated**: 2025-01-22 -**Specification**: Follows the AGENTS.md canonical structure +# AGENTS.md + +Resolver for agent-facing guidance in this repository. Each topic below points +to its canonical location. Keep detailed workflows and task-specific rules in +those locations rather than duplicating them here. + +## What is this repository? + +This monorepo contains the Azure SDK for Python: + +- Service packages live under `sdk///`. +- Engineering tooling lives under `eng/` and `tools/`. +- Contributor and developer documentation lives under `doc/`. +- Agent workflows live in `.github/skills/`. +- Path-scoped review rules live in `.github/instructions/reviewer/`. +- Package-specific knowledge lives under + `sdk///.github/skills/`. + +Contributor onboarding and repository setup are documented in `README.md` and +`CONTRIBUTING.md`. + +## Where to find guidance + +| Task or topic | Canonical guidance | +| --- | --- | +| Modify any package under `sdk/` | `.github/skills/find-package-skill/SKILL.md` (consult first) | +| Generate, customize, validate, or test an SDK locally | `.github/skills/azsdk-common-generate-sdk-locally/SKILL.md` | +| Generate SDK pull requests through the pipeline | `.github/skills/azsdk-common-generate-sdk-pipeline/SKILL.md` | +| Resolve APIView feedback | `.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md` | +| Analyze a failed CI pipeline | `.github/skills/azsdk-common-pipeline-analysis/SKILL.md` | +| Fix a failed CI pipeline | `.github/skills/azsdk-common-pipeline-fixer/SKILL.md` | +| Create or update a release plan | `.github/skills/azsdk-common-prepare-release-plan/SKILL.md` | +| Check release readiness or release a package | `.github/skills/azsdk-common-sdk-release/SKILL.md` | +| Fix pylint, mypy, Black, or Sphinx failures | `.github/skills/fix-pylint/SKILL.md`, `fix-mypy/SKILL.md`, `fix-black/SKILL.md`, or `fix-sphinx/SKILL.md` | +| Create an API review PR or API markdown | `.github/skills/create-api-review-pr/SKILL.md` or `.github/skills/generate-api-markdown/SKILL.md` | +| Create package-specific agent guidance | `.github/skills/create-package-skill/SKILL.md` | +| Review a management-plane package | `.github/instructions/reviewer/mgmt-sdk.instructions.md` | +| Report package health | `.github/prompts/check-package-health.prompt.md` and `doc/repo_health_status.md` | +| Run repository checks with `azpysdk` | `doc/tool_usage_guide.md` | +| Test SDK packages | `doc/dev/tests.md` | +| Write Python docstrings | `doc/dev/docstring.md` | +| Follow Azure SDK Python API design | https://azure.github.io/azure-sdk/python_design.html | + +Load task-specific guidance on demand. Do not load every skill or deep-dive +document before it is relevant. + +## Hard rules + +- Consult `.github/skills/find-package-skill/SKILL.md` before modifying a + package under `sdk/`, then load any package-specific skill it discovers. +- Do not directly customize generated SDK files. Use the generation and + customization workflow, and place hand-written changes in the supported + customization layer for that package. +- Use `azpysdk` for repository checks. Follow `doc/tool_usage_guide.md` and the + task-specific fix skill rather than reviving older tox-based commands. +- Treat the Azure SDK Python Design Guidelines as the authoritative API design + reference. Link to the relevant section when answering design-guideline + questions. +- Before using Azure SDK MCP tools from Visual Studio or VS Code, ensure + [PowerShell is installed](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) + and run `azure-sdk-mcp:azsdk_verify_setup`. This setup check is not required + for GitHub-hosted coding agents or requests that do not use MCP tools. +- Keep management-plane review rules scoped to + `sdk/*/azure-mgmt-*/`; do not apply them to data-plane packages. +- Use current Azure SDK skills and MCP tool names from those skills. Do not copy + tool contracts into general repository guidance. + +## Where new guidance belongs + +- A workflow for a specific task type belongs in a skill under + `.github/skills/`. +- Review-only behavior belongs in a path-scoped file under + `.github/instructions/reviewer/`. +- Package-specific architecture, customization, and verification knowledge + belongs in the package's `.github/skills/` directory. +- Contributor setup, prerequisites, and human-oriented procedures belong in + `CONTRIBUTING.md` or `doc/`. +- A short, repository-wide rule belongs in this file only when it cannot live + in a more specific location. + +If a fact appears to belong in two places, keep it in the more specific +location and link to it from the more general one.