docs: enhance copilot-instructions with build commands and architecture#3640
docs: enhance copilot-instructions with build commands and architecture#3640
Conversation
Add Build, Test, and Lint section with common cargo commands including how to run a single test and record integration tests. Add Architecture section explaining core crates, service crates, and the identity crate hierarchy. Add Integration Tests section covering #[recorded::test] usage. Add Error Handling section with azure_core::Result<T> convention. Remove Prerequisites section about MCP servers.
j7nw4r
requested review from
LarryOsterman,
RickWinter,
heaths and
ronniegeraghty
as code owners
There was a problem hiding this comment.
Pull request overview
This PR enhances the .github/copilot-instructions.md file with practical quick-reference information for developers using GitHub Copilot with the Azure SDK for Rust codebase.
Changes:
- Added build, test, and lint commands with practical cargo examples
- Added architecture overview describing core crates, service crates, and identity crate organization
- Added integration testing documentation explaining
#[recorded::test]usage and recording workflow - Added error handling conventions for service crates and examples
- Removed the Prerequisites section about MCP servers
| - **Service crates** (`sdk/<service>/<crate>/`): Azure service clients (e.g., `azure_security_keyvault_secrets`). | ||
| - Most contain a `generated/` subdirectory with TypeSpec-generated code — **never edit these files**. | ||
| - Hand-written code in `src/` adds convenience methods or customizations. | ||
| - **Identity crate** (`sdk/identity/azure_identity`): Authentication via `DefaultAzureCredential` and related types. |
There was a problem hiding this comment.
The reference to DefaultAzureCredential is incorrect for the Rust SDK. The Rust SDK uses DeveloperToolsCredential as the primary credential for development scenarios, not DefaultAzureCredential. Update this line to reference DeveloperToolsCredential and other available credentials (like ManagedIdentityCredential for production scenarios) to accurately reflect the Rust SDK's identity crate structure.
| - **Identity crate** (`sdk/identity/azure_identity`): Authentication via `DefaultAzureCredential` and related types. | |
| - **Identity crate** (`sdk/identity/azure_identity`): Authentication via `DeveloperToolsCredential`, `ManagedIdentityCredential`, and other identity types. |
| ## Integration Tests | ||
|
|
||
| - Integration tests go in a crate's `tests/` directory and use `#[recorded::test]` (from `azure_core_test`). | ||
| - Recorded tests replay HTTP traffic from recordings in `sdk/<service>/assets/` (referenced via `assets.json`). |
There was a problem hiding this comment.
The statement about recordings being in sdk/<service>/assets/ is inaccurate. Recordings are stored in an external repository (Azure/azure-sdk-assets) and referenced via the assets.json file. The recordings are not stored in a local assets/ subdirectory. Consider rephrasing to clarify that recordings are managed via assets.json which points to recordings in the azure-sdk-assets repository.
| - Recorded tests replay HTTP traffic from recordings in `sdk/<service>/assets/` (referenced via `assets.json`). | |
| - Recorded tests replay HTTP traffic from recordings stored in the external `Azure/azure-sdk-assets` repository, as mapped by the per-service `assets.json` file. |
heaths
left a comment
heaths
left a comment
There was a problem hiding this comment.
This was already in AGENTS.md - or at least most of it was. VSCode uses both. Was that not working for you?
|
@scbedd @weshaggard what do you think about putting general "how to provision test resources" in https://github.com/Azure/azure-sdk-for-rust/tree/main/eng/common/instructions that we can link to from @j7nw4r generally we want to keep |
2 participants
Summary
Enhance .github/copilot-instructions.md\ with practical information for Copilot sessions.
Changes
The file continues to reference \AGENTS.md\ for comprehensive details while providing quick-reference information useful during active coding.