From 3c542feebfe453a9ca965a894aa6711f185f01e1 Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:18:58 -0700 Subject: [PATCH 1/5] Add storage-level AGENTS.md guidance for AI contributors --- sdk/storage/AGENTS.md | 108 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 sdk/storage/AGENTS.md diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md new file mode 100644 index 00000000000..d0c1084863a --- /dev/null +++ b/sdk/storage/AGENTS.md @@ -0,0 +1,108 @@ +# AGENTS.md – Storage crates guidance + +This file provides AI-agent guidance for work under `sdk/storage/*`. +It complements the repository root guidance and should be read together with root-level instructions. + +## Scope + +- Applies to all storage crates under `sdk/storage/*`. +- Crate-specific details should live in each crate folder's own `AGENTS.md` (for example, `sdk/storage/azure_storage_blob/AGENTS.md`). + +## Storage family map + +- `azure_storage` – shared storage primitives and common concepts. +- `azure_storage_blob` – Blob Storage client library. +- Other storage crates (queue/file/share/etc.) should follow the same design and testing patterns where applicable. + +## Architecture and API conventions + +- Keep public API style consistent across storage crates. + - Prefer clear builder-based option patterns for operations with optional parameters. + - Keep method naming aligned with service operations and existing crate naming. + - Preserve pagination ergonomics and predictable return types. +- Prefer composition and reusable helpers in internal modules over duplicating request-building code. +- Keep transport/pipeline usage aligned with `azure_core` patterns used in the repo. + +## Error handling + +- Use `azure_core::Result` for fallible public operations. +- Map service/HTTP failures consistently to `azure_core::Error` and existing error categorization patterns. +- Preserve retry behavior expectations; avoid introducing ad-hoc retry logic in operation methods. + +## Authentication and request setup + +- Respect existing credential flows used by storage crates (AAD, SAS, connection string, shared key where supported). +- Ensure new options are correctly represented in headers/query strings and signed/authenticated where required. +- For cross-crate auth behavior changes, keep semantics consistent across storage crates. + +## Generated vs hand-written code + +- Do **not** manually edit generated code paths/files when generation is the source of truth. +- If a change must be generated, update the source inputs and regenerate according to repo guidance. +- Keep hand-written customization in the intended extension points. + +## Testing strategy + +- Add/maintain unit tests for isolated behavior and serialization/parsing logic. +- Add/maintain recorded/live tests for service-integration behavior where appropriate. +- Reuse existing test helpers and fixtures before adding new ones. +- Keep tests deterministic and minimize time/network sensitivity. + +## Quality bar before handoff + +From repo root (or scoped to affected crates as appropriate): + +- `cargo fmt` +- `cargo clippy -p --all-targets --all-features` +- `cargo test -p ` + +When touching multiple crates, run checks for each affected crate. + +## Common pitfalls + +- Inconsistent option naming across similar operations/crates. +- Breaking changes to public API shape for convenience-only refactors. +- Missing tests for new optional headers/query parameters. +- Diverging behavior between similar storage operations in different crates. + +## Agent task playbooks + +### 1) Add a new optional request header/parameter + +1. Locate the operation options/builder type. +2. Add the new field with clear docs and sensible default (`None` when optional). +3. Thread it into request construction (header/query) in one place. +4. Add unit tests for request construction and a service-level test when required. +5. Verify no behavioral change when option is unset. + +### 2) Add a new listing/pagination option + +1. Extend options type and docs. +2. Apply to request query construction. +3. Validate continuation token behavior remains unchanged. +4. Add tests for first and continuation requests where possible. + +### 3) Adjust response model/deserialization + +1. Keep backward compatibility for public fields/types unless intentionally versioned. +2. Prefer additive changes. +3. Add regression tests for missing/extra/unknown fields as needed. + +### 4) Update retryable error classification + +1. Align with existing `azure_core`/pipeline strategy. +2. Avoid operation-specific special casing unless unavoidable and documented. +3. Add tests for representative status/error cases. + +### 5) Add a new operation end-to-end + +1. Follow existing operation module layout and naming. +2. Define request/options/response types consistent with neighboring operations. +3. Add docs with minimal, runnable-style usage examples when practical. +4. Add unit tests and recorded/live tests where the crate pattern expects them. + +## When in doubt + +- Follow adjacent storage crate patterns first. +- Prefer consistency with existing public APIs over introducing a new style. +- Document assumptions in code comments or PR notes when behavior is service-specific. From 1e44e5a5b574340bd0eb34faf6d5a9902b63e23e Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:23:49 -0700 Subject: [PATCH 2/5] Add blob-specific AGENTS.md guidance --- sdk/storage/azure_storage_blob/AGENTS.md | 114 +++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 sdk/storage/azure_storage_blob/AGENTS.md diff --git a/sdk/storage/azure_storage_blob/AGENTS.md b/sdk/storage/azure_storage_blob/AGENTS.md new file mode 100644 index 00000000000..a687cab87d9 --- /dev/null +++ b/sdk/storage/azure_storage_blob/AGENTS.md @@ -0,0 +1,114 @@ +# AGENTS.md – Blob Storage crate guidance + +This file provides AI-agent guidance for work under `sdk/storage/azure_storage_blob/*`. +It supplements repository-root guidance and `sdk/storage/AGENTS.md` with Blob Storage crate-specific expectations. + +## Scope + +- Applies to the `azure_storage_blob` crate. +- Use this file together with the repository root `AGENTS.md` and `sdk/storage/AGENTS.md`. +- When instructions conflict, follow the more specific guidance in this directory for blob-specific code. + +## Crate focus + +- This crate implements the Azure Blob Storage client library. +- Keep behavior and API shape aligned with Blob Storage concepts such as containers, blobs, snapshots, versions, leases, tags, block operations, and listing semantics. +- Prefer consistency with adjacent blob operations over introducing a new pattern for a single API. + +## API design conventions + +- Keep public APIs ergonomic and predictable for common blob workflows. +- Follow existing naming and module patterns for container-level and blob-level operations. +- Prefer builder/options patterns for optional request parameters. +- Keep request and response model names aligned with service terminology and neighboring blob operations. +- Preserve pagination behavior and continuation token handling conventions used elsewhere in the crate. + +## Request construction and protocol details + +- Ensure optional blob request parameters are threaded consistently into headers and query parameters. +- Be careful with conditional request semantics (`If-Match`, `If-None-Match`, modified-since, lease conditions, etc.). +- Treat versioning, snapshots, ranges, content headers, metadata, and tags as protocol-sensitive areas that need targeted tests. +- Keep URL/path handling and resource naming consistent with existing blob request builders. +- Avoid duplicating request-building logic when shared helpers or existing operation patterns already exist. + +## Data model and compatibility + +- Prefer additive changes to public request/response types. +- Avoid breaking changes to public structs, enums, or method signatures unless explicitly intended. +- Keep deserialization resilient to optional or newly added service fields where existing crate patterns allow. +- Maintain backward-compatible behavior for existing defaults and unset optional fields. + +## Authentication and authorization considerations + +- Respect existing credential flows supported by the storage libraries. +- For SAS- or signature-sensitive changes, verify that new headers/query parameters are included where required by existing signing/auth behavior. +- Do not introduce blob-specific auth behavior that diverges from shared storage crate expectations without clear justification. + +## Testing expectations + +- Add unit tests for request construction, option propagation, and serialization/deserialization behavior. +- Add or update recorded/live tests for service behaviors that cannot be validated through isolated unit tests. +- Favor narrow regression tests for blob-specific semantics like ranges, metadata, tags, conditions, leases, copy flows, and listing behavior. +- Reuse existing blob test helpers, fixtures, and crate patterns before adding new infrastructure. + +## Common blob-specific pitfalls + +- Inconsistent handling of container vs blob scopes. +- Missing propagation of optional headers or query parameters. +- Incorrect continuation token behavior for listing operations. +- Breaking response or option shapes for convenience refactors. +- Incomplete coverage for lease, conditional, range, snapshot, or version-related behavior. +- Subtle behavior drift between similar operations that should remain consistent. + +## Suggested file and code reading order + +When making a blob-specific change: + +1. Start from the neighboring operation/module that most closely matches the target behavior. +2. Reuse existing option, request-building, and response-model patterns where possible. +3. Check tests for adjacent operations before inventing a new testing style. +4. If shared logic is needed, prefer factoring into existing internal helpers over copying code. + +## Agent task playbooks + +### 1) Add a new optional blob request option + +1. Extend the relevant options/builder type. +2. Document the option clearly and keep the default behavior unchanged. +3. Thread the option into header/query construction in one place. +4. Add unit tests for the serialized request shape. +5. Add service-level coverage if the behavior is protocol-sensitive. + +### 2) Add or adjust blob listing behavior + +1. Match existing listing APIs and terminology. +2. Preserve continuation token semantics. +3. Verify option propagation for both initial and continuation requests. +4. Add regression coverage for any changed filtering/detail flags. + +### 3) Update blob response parsing + +1. Keep public model changes additive whenever possible. +2. Validate behavior with representative payloads, including partial/optional fields. +3. Add regression tests for service-specific edge cases. + +### 4) Add a new blob/container operation + +1. Follow neighboring module naming and layout. +2. Keep request/options/response types aligned with crate conventions. +3. Add concise docs and examples when the surrounding crate pattern expects them. +4. Add unit and integration-style tests consistent with similar operations. + +## Before handoff + +From repo root, run or recommend the checks most relevant to the crate: + +- `cargo fmt` +- `cargo clippy -p azure_storage_blob --all-targets --all-features` +- `cargo test -p azure_storage_blob` + +## When in doubt + +- Follow existing `azure_storage_blob` patterns first. +- Prefer consistency with neighboring blob APIs over introducing a one-off abstraction. +- If a change seems broadly applicable across storage crates, reflect that in `sdk/storage/AGENTS.md` rather than only here. From 644ee29dbe3c67c41223504d6b252d531fb87d3c Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Thu, 16 Jul 2026 13:34:10 -0700 Subject: [PATCH 3/5] Revise AGENTS.md for blob storage guidance Refactor blob-specific guidance in AGENTS.md to clarify scope, expectations, and testing requirements. --- sdk/storage/azure_storage_blob/AGENTS.md | 131 ++++++----------------- 1 file changed, 34 insertions(+), 97 deletions(-) diff --git a/sdk/storage/azure_storage_blob/AGENTS.md b/sdk/storage/azure_storage_blob/AGENTS.md index a687cab87d9..e3792087d67 100644 --- a/sdk/storage/azure_storage_blob/AGENTS.md +++ b/sdk/storage/azure_storage_blob/AGENTS.md @@ -1,114 +1,51 @@ # AGENTS.md – Blob Storage crate guidance -This file provides AI-agent guidance for work under `sdk/storage/azure_storage_blob/*`. -It supplements repository-root guidance and `sdk/storage/AGENTS.md` with Blob Storage crate-specific expectations. +This file provides blob-specific guidance for work under `sdk/storage/azure_storage_blob/*`. -## Scope - -- Applies to the `azure_storage_blob` crate. -- Use this file together with the repository root `AGENTS.md` and `sdk/storage/AGENTS.md`. -- When instructions conflict, follow the more specific guidance in this directory for blob-specific code. - -## Crate focus - -- This crate implements the Azure Blob Storage client library. -- Keep behavior and API shape aligned with Blob Storage concepts such as containers, blobs, snapshots, versions, leases, tags, block operations, and listing semantics. -- Prefer consistency with adjacent blob operations over introducing a new pattern for a single API. - -## API design conventions - -- Keep public APIs ergonomic and predictable for common blob workflows. -- Follow existing naming and module patterns for container-level and blob-level operations. -- Prefer builder/options patterns for optional request parameters. -- Keep request and response model names aligned with service terminology and neighboring blob operations. -- Preserve pagination behavior and continuation token handling conventions used elsewhere in the crate. - -## Request construction and protocol details - -- Ensure optional blob request parameters are threaded consistently into headers and query parameters. -- Be careful with conditional request semantics (`If-Match`, `If-None-Match`, modified-since, lease conditions, etc.). -- Treat versioning, snapshots, ranges, content headers, metadata, and tags as protocol-sensitive areas that need targeted tests. -- Keep URL/path handling and resource naming consistent with existing blob request builders. -- Avoid duplicating request-building logic when shared helpers or existing operation patterns already exist. - -## Data model and compatibility - -- Prefer additive changes to public request/response types. -- Avoid breaking changes to public structs, enums, or method signatures unless explicitly intended. -- Keep deserialization resilient to optional or newly added service fields where existing crate patterns allow. -- Maintain backward-compatible behavior for existing defaults and unset optional fields. +Use this together with: +- repository root `AGENTS.md` +- `sdk/storage/AGENTS.md` -## Authentication and authorization considerations +If guidance conflicts, follow the more specific instructions in this directory. -- Respect existing credential flows supported by the storage libraries. -- For SAS- or signature-sensitive changes, verify that new headers/query parameters are included where required by existing signing/auth behavior. -- Do not introduce blob-specific auth behavior that diverges from shared storage crate expectations without clear justification. - -## Testing expectations - -- Add unit tests for request construction, option propagation, and serialization/deserialization behavior. -- Add or update recorded/live tests for service behaviors that cannot be validated through isolated unit tests. -- Favor narrow regression tests for blob-specific semantics like ranges, metadata, tags, conditions, leases, copy flows, and listing behavior. -- Reuse existing blob test helpers, fixtures, and crate patterns before adding new infrastructure. - -## Common blob-specific pitfalls - -- Inconsistent handling of container vs blob scopes. -- Missing propagation of optional headers or query parameters. -- Incorrect continuation token behavior for listing operations. -- Breaking response or option shapes for convenience refactors. -- Incomplete coverage for lease, conditional, range, snapshot, or version-related behavior. -- Subtle behavior drift between similar operations that should remain consistent. - -## Suggested file and code reading order - -When making a blob-specific change: - -1. Start from the neighboring operation/module that most closely matches the target behavior. -2. Reuse existing option, request-building, and response-model patterns where possible. -3. Check tests for adjacent operations before inventing a new testing style. -4. If shared logic is needed, prefer factoring into existing internal helpers over copying code. - -## Agent task playbooks - -### 1) Add a new optional blob request option +## Scope -1. Extend the relevant options/builder type. -2. Document the option clearly and keep the default behavior unchanged. -3. Thread the option into header/query construction in one place. -4. Add unit tests for the serialized request shape. -5. Add service-level coverage if the behavior is protocol-sensitive. +- Applies only to the `azure_storage_blob` crate. +- Do not repeat storage-wide guidance here; keep shared conventions in `sdk/storage/AGENTS.md`. -### 2) Add or adjust blob listing behavior +## Blob-specific focus areas -1. Match existing listing APIs and terminology. -2. Preserve continuation token semantics. -3. Verify option propagation for both initial and continuation requests. -4. Add regression coverage for any changed filtering/detail flags. +- Keep behavior aligned with Blob Storage concepts: containers, blobs, snapshots, versions, leases, tags, ranges, block operations, and listing semantics. +- Prefer consistency with neighboring blob/container operations over introducing one-off patterns. -### 3) Update blob response parsing +## Protocol-sensitive areas -1. Keep public model changes additive whenever possible. -2. Validate behavior with representative payloads, including partial/optional fields. -3. Add regression tests for service-specific edge cases. +Be especially careful with: -### 4) Add a new blob/container operation +- conditional request semantics (lease conditions) +- snapshot and version handling +- range requests and content headers +- metadata and tags +- continuation tokens for listing operations +- container-scope vs blob-scope behavior -1. Follow neighboring module naming and layout. -2. Keep request/options/response types aligned with crate conventions. -3. Add concise docs and examples when the surrounding crate pattern expects them. -4. Add unit and integration-style tests consistent with similar operations. +## Blob-specific expectations -## Before handoff +- Start from the closest existing blob or container operation and mirror its API, request construction, and tests. +- Reuse shared helpers and existing request-building patterns before introducing new abstractions. +- Keep public model changes additive unless a breaking change is explicitly intended. -From repo root, run or recommend the checks most relevant to the crate: +## Blob-specific pitfalls -- `cargo fmt` -- `cargo clippy -p azure_storage_blob --all-targets --all-features` -- `cargo test -p azure_storage_blob` +- Mixing up container-level and blob-level semantics +- Missing propagation of optional headers or query parameters +- Incorrect continuation token handling in listing flows +- Inconsistent behavior across similar blob operations +- Insufficient coverage for lease, conditional, range, snapshot, version, metadata, or tag behavior -## When in doubt +## Suggested workflow for changes -- Follow existing `azure_storage_blob` patterns first. -- Prefer consistency with neighboring blob APIs over introducing a one-off abstraction. -- If a change seems broadly applicable across storage crates, reflect that in `sdk/storage/AGENTS.md` rather than only here. +1. Find the most similar existing blob/container operation. +2. Reuse its options, request construction, and response patterns where possible. +3. Add focused regression tests for the blob-specific protocol behavior being changed. +4. If guidance is broadly applicable to all storage crates, move it to `sdk/storage/AGENTS.md` instead of duplicating it here. From f456860e868e278971dfa87ad69f89c0d6b0a84c Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Thu, 16 Jul 2026 13:34:43 -0700 Subject: [PATCH 4/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- sdk/storage/AGENTS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md index d0c1084863a..9875e6e3e44 100644 --- a/sdk/storage/AGENTS.md +++ b/sdk/storage/AGENTS.md @@ -10,9 +10,11 @@ It complements the repository root guidance and should be read together with roo ## Storage family map -- `azure_storage` – shared storage primitives and common concepts. +- `azure_storage_common` – shared storage primitives and common types. - `azure_storage_blob` – Blob Storage client library. -- Other storage crates (queue/file/share/etc.) should follow the same design and testing patterns where applicable. +- `azure_storage_queue` – Queue Storage client library. +- `azure_storage_sas` – Shared Access Signature (SAS) builder for Azure Storage services. +- Additional storage crates should follow the same design and testing patterns where applicable. ## Architecture and API conventions From 224c75ba5a9e266283795454aff9db08ed8f1778 Mon Sep 17 00:00:00 2001 From: Amanda Nguyen <48961492+amnguye@users.noreply.github.com> Date: Thu, 16 Jul 2026 13:42:30 -0700 Subject: [PATCH 5/5] Simplify AGENTS.md for storage crates guidance Condensed guidance for storage crates, focusing on consistency and minimalism. Removed redundant sections and clarified instructions for crate-specific details. --- sdk/storage/AGENTS.md | 133 +++++++++++++----------------------------- 1 file changed, 42 insertions(+), 91 deletions(-) diff --git a/sdk/storage/AGENTS.md b/sdk/storage/AGENTS.md index 9875e6e3e44..09acf0f6fa5 100644 --- a/sdk/storage/AGENTS.md +++ b/sdk/storage/AGENTS.md @@ -1,110 +1,61 @@ -# AGENTS.md – Storage crates guidance +# AGENTS.md – Storage crates guidance (minimal) -This file provides AI-agent guidance for work under `sdk/storage/*`. -It complements the repository root guidance and should be read together with root-level instructions. +Storage-specific guidance for `sdk/storage/*`. -## Scope - -- Applies to all storage crates under `sdk/storage/*`. -- Crate-specific details should live in each crate folder's own `AGENTS.md` (for example, `sdk/storage/azure_storage_blob/AGENTS.md`). - -## Storage family map - -- `azure_storage_common` – shared storage primitives and common types. -- `azure_storage_blob` – Blob Storage client library. -- `azure_storage_queue` – Queue Storage client library. -- `azure_storage_sas` – Shared Access Signature (SAS) builder for Azure Storage services. -- Additional storage crates should follow the same design and testing patterns where applicable. - -## Architecture and API conventions - -- Keep public API style consistent across storage crates. - - Prefer clear builder-based option patterns for operations with optional parameters. - - Keep method naming aligned with service operations and existing crate naming. - - Preserve pagination ergonomics and predictable return types. -- Prefer composition and reusable helpers in internal modules over duplicating request-building code. -- Keep transport/pipeline usage aligned with `azure_core` patterns used in the repo. - -## Error handling - -- Use `azure_core::Result` for fallible public operations. -- Map service/HTTP failures consistently to `azure_core::Error` and existing error categorization patterns. -- Preserve retry behavior expectations; avoid introducing ad-hoc retry logic in operation methods. - -## Authentication and request setup +Root `AGENTS.md` is authoritative for repo-wide rules (generated code, compatibility, security, lint/test/CI, and general coding standards). Do not repeat those rules here. -- Respect existing credential flows used by storage crates (AAD, SAS, connection string, shared key where supported). -- Ensure new options are correctly represented in headers/query strings and signed/authenticated where required. -- For cross-crate auth behavior changes, keep semantics consistent across storage crates. - -## Generated vs hand-written code - -- Do **not** manually edit generated code paths/files when generation is the source of truth. -- If a change must be generated, update the source inputs and regenerate according to repo guidance. -- Keep hand-written customization in the intended extension points. - -## Testing strategy - -- Add/maintain unit tests for isolated behavior and serialization/parsing logic. -- Add/maintain recorded/live tests for service-integration behavior where appropriate. -- Reuse existing test helpers and fixtures before adding new ones. -- Keep tests deterministic and minimize time/network sensitivity. - -## Quality bar before handoff - -From repo root (or scoped to affected crates as appropriate): - -- `cargo fmt` -- `cargo clippy -p --all-targets --all-features` -- `cargo test -p ` +## Scope -When touching multiple crates, run checks for each affected crate. +- Applies to all crates under `sdk/storage/*`. +- Put crate-specific details in each crate’s local `AGENTS.md`. -## Common pitfalls +## Storage consistency requirements -- Inconsistent option naming across similar operations/crates. -- Breaking changes to public API shape for convenience-only refactors. -- Missing tests for new optional headers/query parameters. -- Diverging behavior between similar storage operations in different crates. +- Keep API shape consistent across storage crates: + - Similar operations should use similar option/builder patterns. + - Use consistent naming for equivalent concepts. + - Keep pagination behavior/ergonomics consistent. -## Agent task playbooks +- Reuse shared request-construction helpers where possible; avoid copy/paste request logic. -### 1) Add a new optional request header/parameter +- Preserve storage auth semantics across crates (AAD, SAS, connection string, shared key where supported), including correct header/query threading and signing behavior. -1. Locate the operation options/builder type. -2. Add the new field with clear docs and sensible default (`None` when optional). -3. Thread it into request construction (header/query) in one place. -4. Add unit tests for request construction and a service-level test when required. -5. Verify no behavioral change when option is unset. +## Tests (storage-focused) -### 2) Add a new listing/pagination option +- Add unit tests for request construction and option threading. +- Add/maintain recorded or live tests for service behavior when expected by crate patterns. +- Guard pagination/continuation behavior with tests. -1. Extend options type and docs. -2. Apply to request query construction. -3. Validate continuation token behavior remains unchanged. -4. Add tests for first and continuation requests where possible. +## Common storage pitfalls -### 3) Adjust response model/deserialization +- Option naming drift across crates. +- Behavior drift for equivalent operations in different crates. +- Missing tests for newly added headers/query params. +- Pagination regressions (continuation tokens / next-page behavior). -1. Keep backward compatibility for public fields/types unless intentionally versioned. -2. Prefer additive changes. -3. Add regression tests for missing/extra/unknown fields as needed. +## Minimal playbooks -### 4) Update retryable error classification +### Add optional header/query option +1. Add to options/builder with default `None`. +2. Thread into request construction once (single canonical path). +3. Add request-construction tests. +4. Confirm no behavior change when unset. -1. Align with existing `azure_core`/pipeline strategy. -2. Avoid operation-specific special casing unless unavoidable and documented. -3. Add tests for representative status/error cases. +### Add pagination option +1. Extend options/docs. +2. Apply in query construction. +3. Verify continuation behavior unchanged. +4. Add first-page + continuation tests. -### 5) Add a new operation end-to-end +### Change response/deserialization +1. Prefer additive/backward-compatible changes. +2. Add regression tests for compatibility edge cases. -1. Follow existing operation module layout and naming. -2. Define request/options/response types consistent with neighboring operations. -3. Add docs with minimal, runnable-style usage examples when practical. -4. Add unit tests and recorded/live tests where the crate pattern expects them. +### Add operation +1. Follow neighboring storage operation structure and naming. +2. Keep request/options/response style aligned with adjacent operations. +3. Add unit + service-level tests per crate conventions. -## When in doubt +## When unsure -- Follow adjacent storage crate patterns first. -- Prefer consistency with existing public APIs over introducing a new style. -- Document assumptions in code comments or PR notes when behavior is service-specific. +Prefer existing patterns in adjacent storage crates and document any service-specific deviations.