From 1b4ef15d53539c84875f1b5c7fa7e6563d9a9e69 Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Tue, 7 Jul 2026 17:46:35 -0700 Subject: [PATCH 1/3] Add storage AGENTS.md guidance files for shared, blobs, datalake, and files shares packages --- sdk/storage/AGENTS.md | 144 ++++++++++++++++++ sdk/storage/azure-storage-blobs/AGENTS.md | 103 +++++++++++++ sdk/storage/azure-storage-datalake/AGENTS.md | 104 +++++++++++++ .../azure-storage-files-shares/AGENTS.md | 99 ++++++++++++ 4 files changed, 450 insertions(+) create mode 100644 sdk/storage/AGENTS.md create mode 100644 sdk/storage/azure-storage-blobs/AGENTS.md create mode 100644 sdk/storage/azure-storage-datalake/AGENTS.md create mode 100644 sdk/storage/azure-storage-files-shares/AGENTS.md diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md new file mode 100644 index 0000000000..de839f2cf7 --- /dev/null +++ b/sdk/storage/AGENTS.md @@ -0,0 +1,144 @@ +# AGENTS.md + +This file provides guidance for AI agents working in `sdk/storage` of the Azure SDK for C++ repository. + +## Scope + +This AGENTS file applies to: + +- `sdk/storage/*` +- Cross-cutting storage concepts shared across blobs, files shares, datalake, queues, and storage common. + +This file supplements the repository-root guidance in `/AGENTS.md`. +Agents working in `sdk/storage` must follow both files: apply root repository-wide policies first, then apply storage-specific guidance from this file. + +For service-specific guidance, prefer the local AGENTS files: + +- `sdk/storage/azure-storage-blobs/AGENTS.md` +- `sdk/storage/azure-storage-datalake/AGENTS.md` +- `sdk/storage/azure-storage-files-shares/AGENTS.md` + +If guidance conflicts, the most local AGENTS file takes precedence. + +--- + +## Storage Architecture Basics (C++ SDK) + +Azure Storage packages in this repo generally follow this layering: + +1. **azure-core** + HTTP pipeline, credentials, retries, diagnostics, policies, transport abstractions. + +2. **azure-storage-common** + Shared storage primitives (SAS helpers, shared key auth policy integrations, common request/response helpers, shared models). + +3. **Service libraries** + - `azure-storage-blobs` + - `azure-storage-files-datalake` + - `azure-storage-files-shares` + - `azure-storage-queues` + +### Typical client structure + +Storage libraries commonly expose: + +- **Service clients** (account/service-level operations) +- **Container/share/filesystem clients** (scope-level operations) +- **Item clients** (blob/file/path/message operations) +- **Options/Models** for API inputs and outputs + +Maintain consistency with existing naming, API style, and option-object patterns. + +--- + +## Agent Priorities + +When making changes, prioritize: + +1. **API consistency** with surrounding storage clients. +2. **Minimal diff** and surgical edits. +3. **Backward compatibility** for public APIs. +4. **Tests first/with changes** (unit + live/recording updates as needed). +5. **Documentation and changelog updates** where required. + +--- + +## Do / Don’t + +### Do + +- Follow existing patterns in neighboring storage packages before introducing new abstractions. +- Reuse shared helpers in `azure-storage-common` when appropriate. +- Keep error handling aligned with azure-core and existing storage behavior. +- Preserve ABI/API compatibility unless explicitly requested and reviewed. +- Add or update tests for every functional change. +- Keep generated code and hand-written code boundaries intact. + +### Don’t + +- Don’t introduce breaking public API changes without explicit review. +- Don’t duplicate common logic that belongs in storage common. +- Don’t hardcode secrets, account keys, SAS tokens, or connection strings. +- Don’t manually edit generated assets when source-generation workflow is expected. +- Don’t broaden scope into unrelated storage services in one change. + +--- + +## Key Concepts Agents Should Understand + +- **Authentication modes:** Shared Key, SAS, TokenCredential (Microsoft Entra ID via azure-identity). +- **SAS types:** account SAS, service SAS, user delegation SAS. +- **Conditional requests:** ETag / match conditions. +- **Data integrity:** transactional hashes/validation where supported. +- **Paging:** continuation tokens and pageable responses. +- **Retries/timeouts:** pipeline retry policies and per-call options. +- **Service-version-sensitive behavior:** preserve compatibility and existing defaults. + +--- + +## Testing Guidance + +Before finalizing changes: + +1. Build impacted storage package(s). +2. Run targeted tests for the modified package. +3. If request/response wire behavior changes, ensure playback/recording compatibility strategy is considered. +4. Prefer narrowly scoped tests over broad suite expansion unless needed. + +Use PLAYBACK mode for fast validation where applicable, and only require LIVE/RECORD updates when behavior actually changed. + +--- + +## Expected Change Hygiene + +For non-trivial changes: + +- Update package `CHANGELOG.md`. +- Ensure samples/docs remain accurate. +- Keep includes, namespaces, and public headers aligned with package conventions. +- Validate CMake updates are minimal and correctly scoped to the package. + +--- + +## Escalation / Human Review Triggers + +Flag for maintainer review if change involves: + +- Public API shape changes. +- Authentication/signing logic. +- Retry/pipeline policy semantics. +- Cross-package refactors in multiple storage libraries. +- Service-version default changes. +- Test proxy / recording sanitization policy adjustments. + +--- + +## Quick Checklist for Agents + +- [ ] Scope confirmed to correct storage package. +- [ ] Followed nearest existing code pattern. +- [ ] Added/updated tests. +- [ ] No secrets introduced. +- [ ] No unintended public API break. +- [ ] Changelog/docs updated (if applicable). +- [ ] Build and targeted tests pass locally/CI. diff --git a/sdk/storage/azure-storage-blobs/AGENTS.md b/sdk/storage/azure-storage-blobs/AGENTS.md new file mode 100644 index 0000000000..50190e42b9 --- /dev/null +++ b/sdk/storage/azure-storage-blobs/AGENTS.md @@ -0,0 +1,103 @@ +# AGENTS.md + +Guidance for AI agents working in `sdk/storage/azure-storage-blobs`. + +## Scope + +This file applies to: + +- `sdk/storage/azure-storage-blobs/**` + +It extends `sdk/storage/AGENTS.md` with blob-specific guidance. + +--- + +## Blob Domain Model (mental map) + +Primary client hierarchy typically includes: + +- **BlobServiceClient** (account-level blob service operations) +- **BlobContainerClient** (container-level operations) +- **Blob clients** (blob-level operations), including specializations such as: + - Block blob + - Append blob + - Page blob + +Keep API behavior and naming consistent with this hierarchy. + +--- + +## Blob-Specific Concepts to Preserve + +- **Blob types:** block / append / page have distinct semantics. +- **Upload semantics:** single-shot vs staged/block uploads. +- **Download/range behavior:** partial reads and offset/length options. +- **Leases:** acquire/renew/change/release/break behavior. +- **Snapshots and versions:** immutable references and operation targeting. +- **Soft delete / undelete** and retention interactions. +- **Metadata vs tags:** separate concerns and APIs. +- **Access tiers / rehydration** behavior and option constraints. +- **Copy operations:** sync/async copy patterns and polling/status behavior. + +--- + +## Common Pitfalls (avoid) + +- Mixing block/blob/page operation constraints. +- Breaking conditional header behavior (If-Match, If-None-Match, etc.). +- Inconsistent treatment of empty payloads and zero-length blobs. +- Changing defaults that affect transfer performance or memory behavior. +- Regressing large-transfer chunking/parallel upload logic without benchmarks/tests. + +--- + +## Implementation Guidance + +- Reuse existing upload/download helper logic rather than introducing alternative pathways unless required. +- Keep transfer option parsing and defaults centralized and consistent. +- Maintain compatibility of public models/options and response types. +- Prefer additive changes over replacing established abstractions. + +--- + +## Testing Focus Areas + +When touching blob code, ensure tests cover impacted areas: + +1. Upload/download happy path. +2. Conditional request behavior. +3. Paging/listing continuation flows. +4. Error-path mapping for key service responses. +5. Blob-type-specific behavior (where relevant). +6. Lease/version/snapshot semantics (if modified). + +If behavior changes at protocol level, ensure recording/playback implications are addressed. + +--- + +## API & Compatibility Guardrails + +- Avoid renaming or removing public methods/types without approved breaking-change process. +- Keep overload patterns and option structs aligned with existing blob client style. +- Preserve expected exception/error surfaces unless explicitly justified. + +--- + +## Performance & Reliability Expectations + +- Be cautious with memory allocations for large transfers. +- Keep retry-friendly behavior for transient failures. +- Avoid introducing extra network calls on hot paths. +- Preserve streaming behavior where expected. + +--- + +## Review Triggers + +Explicit human review recommended for: + +- Transfer engine/chunking changes +- Lease logic changes +- Copy/polling workflow changes +- Version/snapshot targeting semantics +- Public API additions/changes diff --git a/sdk/storage/azure-storage-datalake/AGENTS.md b/sdk/storage/azure-storage-datalake/AGENTS.md new file mode 100644 index 0000000000..761aca0627 --- /dev/null +++ b/sdk/storage/azure-storage-datalake/AGENTS.md @@ -0,0 +1,104 @@ +# AGENTS.md + +Guidance for AI agents working in `sdk/storage/azure-storage-datalake`. + +## Scope + +This file applies to: + +- `sdk/storage/azure-storage-datalake/**` + +It extends `sdk/storage/AGENTS.md` with datalake-specific guidance. + +--- + +## Naming and Package Note + +In this repository, Data Lake client code lives under `azure-storage-files-datalake`. +If this AGENTS file is placed in `azure-storage-datalake` for team workflow reasons, ensure changes still target the actual package paths and conventions used by the Data Lake library. + +--- + +## Data Lake Domain Model (mental map) + +Typical hierarchy includes: + +- **DataLakeServiceClient** (account/service scope) +- **FileSystemClient** (filesystem/container scope) +- **Path clients** (file or directory scope), often with dedicated file/directory operations + +Data Lake builds on Blob Storage primitives; maintain alignment where behavior intentionally overlaps. + +--- + +## Data Lake-Specific Concepts to Preserve + +- **Hierarchical namespace semantics** (directories and path operations). +- **Path operations:** create, rename, move, delete. +- **File operations:** append + flush workflow (ordering and position semantics matter). +- **Directory semantics:** recursive operations and path traversal/listing. +- **Access control:** ACLs, permissions, owner/group where applicable. +- **Lease/conditions** behavior when exposed through datalake APIs. +- **SAS/authorization** parity with storage-common/blob foundations where applicable. + +--- + +## Common Pitfalls (avoid) + +- Treating datalake path behavior as identical to flat blob behavior. +- Breaking rename/move atomicity assumptions or destination-conditions handling. +- Mis-handling append/flush offsets and finalization semantics. +- Regressing recursive delete/list behavior with deep trees. +- Inconsistent URL/path encoding treatment for special characters. + +--- + +## Implementation Guidance + +- Follow existing path client patterns for request construction and response parsing. +- Reuse shared storage/common mechanisms for auth/pipeline/retries. +- Keep distinctions between directory and file operations clear and explicit. +- Ensure datalake behavior remains coherent with underlying blob constraints. + +--- + +## Testing Focus Areas + +When modifying datalake code, prioritize tests for: + +1. Path create/delete/list operations (including continuation/paging). +2. Rename/move behavior and conflict/condition handling. +3. Append/flush positional correctness. +4. ACL/permission operations (where touched). +5. Deep directory recursive scenarios (if applicable). +6. Error mapping and exception behavior for common service failures. + +Include edge cases for path encoding and unusual path names when relevant. + +--- + +## API & Compatibility Guardrails + +- Preserve public path/file/directory client API shape and naming conventions. +- Avoid behavioral changes that silently diverge from documented datalake semantics. +- Keep option structs backward compatible and additive when possible. + +--- + +## Reliability Expectations + +- Preserve idempotency where expected. +- Keep retry behavior safe for multi-step operations (append/flush, rename flows). +- Avoid partial-state changes in client abstractions when operations fail mid-flow. + +--- + +## Review Triggers + +Require/flag maintainer review for: + +- Rename/move semantic changes +- Append/flush logic changes +- ACL/permission handling changes +- Public API changes across path clients +- Any cross-library behavior divergence vs blobs/common diff --git a/sdk/storage/azure-storage-files-shares/AGENTS.md b/sdk/storage/azure-storage-files-shares/AGENTS.md new file mode 100644 index 0000000000..ee05a49b6d --- /dev/null +++ b/sdk/storage/azure-storage-files-shares/AGENTS.md @@ -0,0 +1,99 @@ +# AGENTS.md + +Guidance for AI agents working in `sdk/storage/azure-storage-files-shares`. + +## Scope + +This file applies to: + +- `sdk/storage/azure-storage-files-shares/**` + +It extends `sdk/storage/AGENTS.md` with Azure Files (SMB/NFS cloud file share) specific guidance. + +--- + +## File Shares Domain Model (mental map) + +Typical client hierarchy includes: + +- **ShareServiceClient** (service/account scope) +- **ShareClient** (share scope) +- **Directory and File clients** (path/item scope) +- Optional related clients for handles/permissions/snapshots depending on API surface + +Preserve consistency of this hierarchy and existing naming conventions. + +--- + +## File Shares-Specific Concepts to Preserve + +- **Share vs directory vs file** operation boundaries. +- **Create/update ranges** and sparse file range semantics. +- **Handles/sessions** management operations where exposed. +- **SMB/NFS-relevant properties** (permissions/attributes/protocol-oriented metadata as applicable). +- **Snapshots** of shares and snapshot-targeted operations. +- **Quota/provisioning properties** and service/share-level settings. +- **Rename/move semantics** where available in API versions. + +--- + +## Common Pitfalls (avoid) + +- Confusing blob-style operations with file share path/range behaviors. +- Incorrect range write/clear behavior or off-by-one range boundaries. +- Regressing directory traversal/listing with large shares. +- Breaking snapshot-aware request targeting. +- Mis-handling path normalization/encoding for nested directories. + +--- + +## Implementation Guidance + +- Reuse existing request builders and models for range operations. +- Keep directory/file client responsibilities well separated. +- Preserve existing option structs and overload patterns. +- Align error handling with current file shares conventions and azure-core patterns. + +--- + +## Testing Focus Areas + +When modifying file shares code, cover: + +1. Share create/delete/get properties flows. +2. Directory and file CRUD operations. +3. Range upload/clear/download behavior. +4. Listing and paging continuation. +5. Snapshot create/list/targeting behavior (if touched). +6. Protocol/permission-related operations (if touched). +7. Error-path behavior and condition headers. + +Add boundary tests for empty files, large ranges, nested paths, and existing/non-existing resources. + +--- + +## API & Compatibility Guardrails + +- Do not break public client/type names or existing method contracts. +- Keep changes additive when possible. +- Preserve behavioral expectations for range and path operations. + +--- + +## Performance & Reliability Expectations + +- Avoid unnecessary buffering/copies for large file/range operations. +- Keep retries safe for range writes and other potentially non-idempotent calls. +- Avoid adding extra service calls in common path operations. + +--- + +## Review Triggers + +Flag for maintainer review when changes include: + +- Range write/read logic +- Snapshot handling +- Permission/attribute semantics +- Rename/move/path semantics +- Public API changes From b142e91e9433d7f5e0855aa861b08dc7c4c76da5 Mon Sep 17 00:00:00 2001 From: Jinming Hu Date: Wed, 8 Jul 2026 11:34:45 +1000 Subject: [PATCH 2/3] Address PR review: fix scope glob, typo, and relocate datalake AGENTS.md - sdk/storage/AGENTS.md: change scope from sdk/storage/* to sdk/storage/** to cover nested package files - sdk/storage/AGENTS.md: fix typo 'files shares' -> 'file shares' - Move sdk/storage/azure-storage-datalake/AGENTS.md to sdk/storage/azure-storage-files-datalake/AGENTS.md to match the actual package directory - Update scope and naming note in the relocated Data Lake AGENTS.md - Update the reference in sdk/storage/AGENTS.md accordingly Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- sdk/storage/AGENTS.md | 6 +++--- .../AGENTS.md | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) rename sdk/storage/{azure-storage-datalake => azure-storage-files-datalake}/AGENTS.md (88%) diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md index de839f2cf7..85b78e5445 100644 --- a/sdk/storage/AGENTS.md +++ b/sdk/storage/AGENTS.md @@ -6,8 +6,8 @@ This file provides guidance for AI agents working in `sdk/storage` of the Azure This AGENTS file applies to: -- `sdk/storage/*` -- Cross-cutting storage concepts shared across blobs, files shares, datalake, queues, and storage common. +- `sdk/storage/**` +- Cross-cutting storage concepts shared across blobs, file shares, datalake, queues, and storage common. This file supplements the repository-root guidance in `/AGENTS.md`. Agents working in `sdk/storage` must follow both files: apply root repository-wide policies first, then apply storage-specific guidance from this file. @@ -15,7 +15,7 @@ Agents working in `sdk/storage` must follow both files: apply root repository-wi For service-specific guidance, prefer the local AGENTS files: - `sdk/storage/azure-storage-blobs/AGENTS.md` -- `sdk/storage/azure-storage-datalake/AGENTS.md` +- `sdk/storage/azure-storage-files-datalake/AGENTS.md` - `sdk/storage/azure-storage-files-shares/AGENTS.md` If guidance conflicts, the most local AGENTS file takes precedence. diff --git a/sdk/storage/azure-storage-datalake/AGENTS.md b/sdk/storage/azure-storage-files-datalake/AGENTS.md similarity index 88% rename from sdk/storage/azure-storage-datalake/AGENTS.md rename to sdk/storage/azure-storage-files-datalake/AGENTS.md index 761aca0627..6a04f9763b 100644 --- a/sdk/storage/azure-storage-datalake/AGENTS.md +++ b/sdk/storage/azure-storage-files-datalake/AGENTS.md @@ -1,12 +1,12 @@ # AGENTS.md -Guidance for AI agents working in `sdk/storage/azure-storage-datalake`. +Guidance for AI agents working in `sdk/storage/azure-storage-files-datalake`. ## Scope This file applies to: -- `sdk/storage/azure-storage-datalake/**` +- `sdk/storage/azure-storage-files-datalake/**` It extends `sdk/storage/AGENTS.md` with datalake-specific guidance. @@ -14,8 +14,7 @@ It extends `sdk/storage/AGENTS.md` with datalake-specific guidance. ## Naming and Package Note -In this repository, Data Lake client code lives under `azure-storage-files-datalake`. -If this AGENTS file is placed in `azure-storage-datalake` for team workflow reasons, ensure changes still target the actual package paths and conventions used by the Data Lake library. +The Data Lake client code lives under `azure-storage-files-datalake` in this repository. When making changes, ensure paths, includes, namespaces, and conventions target this package. --- From 23de1e4940c5df25d68ce31ae67e7dfb4a06345c Mon Sep 17 00:00:00 2001 From: Jinming Hu Date: Wed, 8 Jul 2026 11:36:29 +1000 Subject: [PATCH 3/3] Ensure AGENTS.md files are pure ASCII Replace curly right-single-quote (U+2019) with ASCII apostrophe in sdk/storage/AGENTS.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- sdk/storage/AGENTS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md index 85b78e5445..a2fb2ea90a 100644 --- a/sdk/storage/AGENTS.md +++ b/sdk/storage/AGENTS.md @@ -63,7 +63,7 @@ When making changes, prioritize: --- -## Do / Don’t +## Do / Don't ### Do @@ -74,13 +74,13 @@ When making changes, prioritize: - Add or update tests for every functional change. - Keep generated code and hand-written code boundaries intact. -### Don’t +### Don't -- Don’t introduce breaking public API changes without explicit review. -- Don’t duplicate common logic that belongs in storage common. -- Don’t hardcode secrets, account keys, SAS tokens, or connection strings. -- Don’t manually edit generated assets when source-generation workflow is expected. -- Don’t broaden scope into unrelated storage services in one change. +- Don't introduce breaking public API changes without explicit review. +- Don't duplicate common logic that belongs in storage common. +- Don't hardcode secrets, account keys, SAS tokens, or connection strings. +- Don't manually edit generated assets when source-generation workflow is expected. +- Don't broaden scope into unrelated storage services in one change. ---