From b2d08bb2454ec574c2d032e0726e1d148705dd9e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Oct 2025 18:39:33 +0000 Subject: [PATCH 1/5] Initial plan From 049216e414611943095fb0a339e269903555c595 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Oct 2025 18:44:24 +0000 Subject: [PATCH 2/5] Add AGENTS.md file with comprehensive AI agent guidance Co-authored-by: ronniegeraghty <28957151+ronniegeraghty@users.noreply.github.com> --- .github/copilot-instructions.md | 2 + AGENTS.md | 340 ++++++++++++++++++++++++++++++++ 2 files changed, 342 insertions(+) create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e7ac30ac02..679c14e253 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,6 +2,8 @@ You are an expert C++ programmer. +For comprehensive guidance on AI agent interactions with this repository, see [AGENTS.md](../AGENTS.md). + ## Repository Structure ### Prerequisites diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..9f4c7f8bb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,340 @@ +# AGENTS.md + +This file provides guidance for AI agents (e.g., GitHub Copilot, LLM-based assistants, and automation tools) interacting with the Azure SDK for C++ repository. + +## Repository Purpose and Scope + +The **Azure SDK for C++** provides modern C++ libraries for Azure services, following the [Azure SDK Design Guidelines for C++](https://azure.github.io/azure-sdk/cpp_introduction.html). This repository contains: + +- **Client libraries** for Azure services (Storage, Key Vault, Identity, etc.) +- **Core libraries** (`azure-core`) providing shared functionality (HTTP pipeline, authentication, retry policies, etc.) +- **Build infrastructure** using CMake and vcpkg +- **Documentation** and samples for developers +- **Test infrastructure** including unit tests and integration tests + +### Key Technologies +- **Language**: C++14 or higher +- **Build System**: CMake (version 3.13+) +- **Package Manager**: vcpkg (manifest mode) +- **Testing**: Google Test (gtest) +- **Documentation**: Doxygen +- **CI/CD**: Azure Pipelines + +## Agent Capabilities and Boundaries + +### ✅ Supported Agent Actions + +AI agents working in this repository are encouraged to: + +1. **Code Contributions** + - Implement new features following the [C++ Guidelines](https://azure.github.io/azure-sdk/cpp_introduction.html) + - Fix bugs with minimal, surgical changes + - Add or update unit tests using Google Test framework + - Improve code documentation using Doxygen-style comments + +2. **Documentation** + - Update README files + - Improve inline code comments + - Update CONTRIBUTING.md when development processes change + - Generate or update API documentation + +3. **Build and Test** + - Run CMake builds locally + - Execute unit tests via `ctest` + - Generate code coverage reports (when BUILD_CODE_COVERAGE is ON) + - Build samples (when BUILD_SAMPLES is ON) + +4. **Code Review and Analysis** + - Review pull requests for adherence to guidelines + - Suggest improvements to code structure and style + - Identify potential issues before CI runs + +### ⚠️ Actions Requiring Caution + +1. **Dependency Management** + - Changing vcpkg.json should be done sparingly + - New dependencies require justification and approval + - OpenSSL version changes need careful consideration + - Consult `vcpkg-custom-ports` for custom dependency versions + +2. **Breaking Changes** + - Public API changes must follow semver and SDK guidelines + - Internal types (in `_internal` namespace) can change within constraints + - Private types (in `_detail` namespace) have fewer restrictions + +3. **CI/CD Configuration** + - Changes to `.github/workflows/` require testing + - Azure Pipeline configurations need validation + - Test proxy configuration changes need verification + +### 🚫 Actions Outside Agent Scope + +Agents should **NOT**: + +1. **Modify Security-Critical Code** without explicit review + - Authentication flows + - Credential handling + - Cryptographic operations + +2. **Make Large Architectural Changes** without design review + - Changing core abstractions + - Modifying HTTP pipeline architecture + - Restructuring repository layout + +3. **Commit Secrets or Sensitive Data** + - No credentials in code or config files + - No API keys in tests (use environment variables) + - No connection strings in source + +## Key Workflows and Commands + +### Building the Project + +```bash +# Basic build +mkdir build && cd build +cmake .. +cmake --build . + +# Build with tests +cmake -DBUILD_TESTING=ON .. +cmake --build . + +# Build with samples +cmake -DBUILD_SAMPLES=ON .. +cmake --build . + +# Build with specific transport adapter +cmake -DBUILD_TRANSPORT_CURL=ON .. +cmake --build . +``` + +### Running Tests + +```bash +# Set test mode (LIVE, PLAYBACK, or RECORD) +export AZURE_TEST_MODE=PLAYBACK + +# Run all tests +ctest -V + +# Run specific package tests +ctest -R azure-core +ctest -R storage + +# Run with test proxy (for recording/playback) +export AZURE_TEST_USE_TEST_PROXY=ON +ctest -V +``` + +### Code Coverage + +```bash +# Build with coverage enabled (requires Debug mode and GNU compiler) +cmake -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DBUILD_CODE_COVERAGE=ON .. +cmake --build . + +# Generate coverage reports +make azure-core_cov_xml # XML report +make azure-core_cov_html # HTML report +``` + +### Documentation Generation + +```bash +# Build Doxygen documentation +cmake -DBUILD_DOCUMENTATION=ON .. +cmake --build . +``` + +### Code Formatting + +```bash +# Format code using clang-format +# The repository includes a .clang-format configuration +find sdk/ -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i +``` + +## Repository Structure + +``` +azure-sdk-for-cpp/ +├── .github/ # GitHub configuration and workflows +│ ├── copilot-instructions.md # Copilot-specific guidance +│ └── workflows/ # CI/CD workflows +├── cmake-modules/ # CMake helper modules +├── doc/ # Documentation +├── eng/ # Engineering system scripts +│ ├── common/ # Shared scripts across Azure SDKs +│ └── docs/ # Documentation generation +├── samples/ # Sample applications +├── sdk/ # SDK service libraries +│ ├── core/ # Core libraries (azure-core, azure-core-amqp, etc.) +│ ├── storage/ # Storage services (blobs, files, queues) +│ ├── identity/ # Authentication and identity +│ ├── keyvault/ # Key Vault (keys, secrets, certificates) +│ └── template/ # Template for new services +├── tools/ # Development tools +├── vcpkg.json # Package dependencies manifest +├── CMakeLists.txt # Root CMake configuration +├── CONTRIBUTING.md # Contribution guidelines +└── AGENTS.md # This file +``` + +## SDK-Specific Automation Workflows + +### 1. Code Generation + +Some SDK components use AutoRest or other code generators: + +- **Swagger/OpenAPI**: Located in `sdk/{service}/swagger/README.md` +- **Protocol Layer**: Auto-generated code in `src/private/` directories +- **Customizations**: Defined via directives in swagger README files + +**Agent Guidance**: Do not manually edit generated files. Modify swagger configurations and regenerate. + +### 2. API Review Process + +Public API changes require: + +1. Update to public header files +2. Doxygen documentation for new APIs +3. Unit tests covering new functionality +4. Sample code demonstrating usage +5. API review approval (tracked externally) + +**Agent Guidance**: Flag API changes for human review. Include APIView links when available. + +### 3. Test Matrix + +Tests run across multiple configurations: + +- **Platforms**: Windows, Linux (Ubuntu), macOS +- **Compilers**: MSVC, GCC, Clang +- **Build Types**: Debug, Release +- **Transport Adapters**: libcurl, WinHTTP +- **Test Modes**: LIVE, PLAYBACK, RECORD + +**Agent Guidance**: Ensure changes work across platforms. Test with both curl and WinHTTP when modifying HTTP layer. + +### 4. Versioning and Releases + +- **Semantic Versioning**: Libraries follow semver (MAJOR.MINOR.PATCH) +- **Version Files**: `src/private/package_version.hpp` in each package +- **Release Tags**: Format `{package-name}_{version}` (e.g., `azure-core_1.10.0`) +- **Changelogs**: `CHANGELOG.md` in each package directory + +**Agent Guidance**: Update version files and changelogs when making changes. Follow [branching strategy](https://github.com/Azure/azure-sdk/blob/main/docs/policies/repobranching.md). + +## Testing Guidelines + +### Test Environment Setup + +Tests require environment variables for authentication and configuration: + +```bash +# Example for Storage tests +export STANDARD_STORAGE_CONNECTION_STRING="..." +export AZURE_STORAGE_ACCOUNT_URL="..." +export AZURE_STORAGE_ACCOUNT_NAME="..." +export AZURE_STORAGE_ACCOUNT_KEY="..." +``` + +See [sdk/core/ci.yml](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/ci.yml) for required configuration per package. + +### Test Modes + +- **PLAYBACK**: Use recorded responses (no network, no credentials needed for actual services) +- **LIVE**: Connect to real Azure services (requires valid credentials) +- **RECORD**: Capture responses for playback (requires test proxy) + +**Agent Guidance**: Use PLAYBACK mode for local development. Use RECORD only when updating test recordings. + +### Test Proxy + +The test proxy (`test-proxy`) enables recording and playback: + +```bash +# Start test proxy automatically +export AZURE_TEST_USE_TEST_PROXY=ON + +# Or start manually +dotnet tool install azure.sdk.tools.testproxy --global +test-proxy start +``` + +See [doc/TestProxy.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/TestProxy.md) for details. + +## Common Development Scenarios + +### Adding a New Service Library + +1. Copy `sdk/template/azure-template/` as starting point +2. Update CMakeLists.txt with new package name +3. Implement service client following SDK guidelines +4. Add unit tests and samples +5. Generate documentation +6. Update root CMakeLists.txt to include new package + +**Agent Guidance**: Follow the template structure. Maintain consistency with existing packages. + +### Fixing a Bug + +1. Add a failing unit test that reproduces the bug +2. Make minimal changes to fix the issue +3. Verify test passes and no regressions +4. Update CHANGELOG.md +5. Submit PR with clear description + +**Agent Guidance**: Keep changes surgical. One bug = one PR. + +### Adding a Feature + +1. Review API design guidelines +2. Create issue or spec doc for large features +3. Implement with tests and documentation +4. Add samples demonstrating usage +5. Update package version and CHANGELOG + +**Agent Guidance**: Get design approval before implementing. Include usage examples. + +## Cross-References + +- **Copilot-Specific Instructions**: [.github/copilot-instructions.md](.github/copilot-instructions.md) +- **Contribution Guide**: [CONTRIBUTING.md](CONTRIBUTING.md) +- **API Design Guidelines**: +- **Test Proxy Documentation**: [doc/TestProxy.md](doc/TestProxy.md) +- **Performance Testing**: [doc/PerformanceTesting.md](doc/PerformanceTesting.md) +- **Distributed Tracing**: [doc/DistributedTracing.md](doc/DistributedTracing.md) + +## Additional Resources + +- **Developer Documentation**: +- **Azure for C++ Developers**: +- **SDK Design Guidelines**: +- **Azure SDK Repository Policies**: +- **Filing Issues**: + +## Agent Best Practices + +1. **Understand Before Changing**: Review existing code and patterns before making changes +2. **Follow Conventions**: Maintain consistency with existing code style and structure +3. **Test Thoroughly**: Run tests locally before submitting changes +4. **Document Changes**: Update comments, docs, and changelogs +5. **Keep Changes Minimal**: Make surgical changes; avoid unnecessary refactoring +6. **Seek Review**: Complex changes should be reviewed by maintainers +7. **Check CI**: Ensure all CI checks pass before merging + +## Metadata + +- **Repository**: +- **Language**: C++14+ +- **License**: MIT +- **Maintainers**: Azure SDK Team +- **Last Updated**: 2025-01-09 + +--- + +This file follows the [AGENTS.md specification](https://agents.md) for standardizing AI agent interactions with repositories. + +For Copilot-specific instructions, see [.github/copilot-instructions.md](.github/copilot-instructions.md). From a936a7f048276a90a6455dafb32e54e1beb073b9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 10 Oct 2025 18:11:43 +0000 Subject: [PATCH 3/5] Fix broken links - replace relative links with full GitHub URLs Co-authored-by: ronniegeraghty <28957151+ronniegeraghty@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- AGENTS.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 679c14e253..7da8b811b0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ You are an expert C++ programmer. -For comprehensive guidance on AI agent interactions with this repository, see [AGENTS.md](../AGENTS.md). +For comprehensive guidance on AI agent interactions with this repository, see [AGENTS.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/AGENTS.md). ## Repository Structure diff --git a/AGENTS.md b/AGENTS.md index 9f4c7f8bb2..dc2a8b119d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -300,12 +300,12 @@ See [doc/TestProxy.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/ ## Cross-References -- **Copilot-Specific Instructions**: [.github/copilot-instructions.md](.github/copilot-instructions.md) -- **Contribution Guide**: [CONTRIBUTING.md](CONTRIBUTING.md) +- **Copilot-Specific Instructions**: [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/.github/copilot-instructions.md) +- **Contribution Guide**: [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md) - **API Design Guidelines**: -- **Test Proxy Documentation**: [doc/TestProxy.md](doc/TestProxy.md) -- **Performance Testing**: [doc/PerformanceTesting.md](doc/PerformanceTesting.md) -- **Distributed Tracing**: [doc/DistributedTracing.md](doc/DistributedTracing.md) +- **Test Proxy Documentation**: [doc/TestProxy.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/TestProxy.md) +- **Performance Testing**: [doc/PerformanceTesting.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/PerformanceTesting.md) +- **Distributed Tracing**: [doc/DistributedTracing.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/DistributedTracing.md) ## Additional Resources @@ -337,4 +337,4 @@ See [doc/TestProxy.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/doc/ This file follows the [AGENTS.md specification](https://agents.md) for standardizing AI agent interactions with repositories. -For Copilot-specific instructions, see [.github/copilot-instructions.md](.github/copilot-instructions.md). +For Copilot-specific instructions, see [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-cpp/blob/main/.github/copilot-instructions.md). From 3b9a686b702d3e73798554f4599befd3b4c5729f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 20:54:55 +0000 Subject: [PATCH 4/5] Replace non-ASCII characters with ASCII equivalents Co-authored-by: ronniegeraghty <28957151+ronniegeraghty@users.noreply.github.com> --- AGENTS.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dc2a8b119d..4b0ca55d48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ The **Azure SDK for C++** provides modern C++ libraries for Azure services, foll ## Agent Capabilities and Boundaries -### ✅ Supported Agent Actions +### Supported Agent Actions AI agents working in this repository are encouraged to: @@ -49,7 +49,7 @@ AI agents working in this repository are encouraged to: - Suggest improvements to code structure and style - Identify potential issues before CI runs -### ⚠️ Actions Requiring Caution +### Actions Requiring Caution 1. **Dependency Management** - Changing vcpkg.json should be done sparingly @@ -67,7 +67,7 @@ AI agents working in this repository are encouraged to: - Azure Pipeline configurations need validation - Test proxy configuration changes need verification -### 🚫 Actions Outside Agent Scope +### Actions Outside Agent Scope Agents should **NOT**: @@ -159,26 +159,26 @@ find sdk/ -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i ``` azure-sdk-for-cpp/ -├── .github/ # GitHub configuration and workflows -│ ├── copilot-instructions.md # Copilot-specific guidance -│ └── workflows/ # CI/CD workflows -├── cmake-modules/ # CMake helper modules -├── doc/ # Documentation -├── eng/ # Engineering system scripts -│ ├── common/ # Shared scripts across Azure SDKs -│ └── docs/ # Documentation generation -├── samples/ # Sample applications -├── sdk/ # SDK service libraries -│ ├── core/ # Core libraries (azure-core, azure-core-amqp, etc.) -│ ├── storage/ # Storage services (blobs, files, queues) -│ ├── identity/ # Authentication and identity -│ ├── keyvault/ # Key Vault (keys, secrets, certificates) -│ └── template/ # Template for new services -├── tools/ # Development tools -├── vcpkg.json # Package dependencies manifest -├── CMakeLists.txt # Root CMake configuration -├── CONTRIBUTING.md # Contribution guidelines -└── AGENTS.md # This file ++-- .github/ # GitHub configuration and workflows + +-- copilot-instructions.md # Copilot-specific guidance + +-- workflows/ # CI/CD workflows ++-- cmake-modules/ # CMake helper modules ++-- doc/ # Documentation ++-- eng/ # Engineering system scripts + +-- common/ # Shared scripts across Azure SDKs + +-- docs/ # Documentation generation ++-- samples/ # Sample applications ++-- sdk/ # SDK service libraries + +-- core/ # Core libraries (azure-core, azure-core-amqp, etc.) + +-- storage/ # Storage services (blobs, files, queues) + +-- identity/ # Authentication and identity + +-- keyvault/ # Key Vault (keys, secrets, certificates) + +-- template/ # Template for new services ++-- tools/ # Development tools ++-- vcpkg.json # Package dependencies manifest ++-- CMakeLists.txt # Root CMake configuration ++-- CONTRIBUTING.md # Contribution guidelines ++-- AGENTS.md # This file ``` ## SDK-Specific Automation Workflows From 075bd7cbea08ac80402ee0187d165cd018b09c86 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 21 Oct 2025 15:43:27 +0000 Subject: [PATCH 5/5] Update code generation section to reflect TypeSpec usage Co-authored-by: RickWinter <4430337+RickWinter@users.noreply.github.com> --- AGENTS.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4b0ca55d48..353630871e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -185,13 +185,14 @@ azure-sdk-for-cpp/ ### 1. Code Generation -Some SDK components use AutoRest or other code generators: +The C++ repository generates SDKs using TypeSpec with the [typespec-cpp emitter](https://github.com/azure/typespec-cpp): -- **Swagger/OpenAPI**: Located in `sdk/{service}/swagger/README.md` -- **Protocol Layer**: Auto-generated code in `src/private/` directories -- **Customizations**: Defined via directives in swagger README files +- **TypeSpec Projects**: Located in package directories with `tspconfig.yaml` and `tsp-location.yaml` files +- **Configuration**: Service-specific settings in `tspconfig.yaml` define emitter options +- **Generated Code**: Auto-generated code in `src/private/` and header directories +- **TypeSpec Emitter**: Uses `@azure-tools/typespec-cpp` with Azure flavor for code generation -**Agent Guidance**: Do not manually edit generated files. Modify swagger configurations and regenerate. +**Agent Guidance**: Do not manually edit generated files. Modify TypeSpec specifications and regenerate using the typespec-cpp emitter. Some older services may still have swagger directories for legacy purposes, but new SDK development uses TypeSpec exclusively. ### 2. API Review Process