Azure · hizixin · May 6, 2026
@@ -1,13 +1,28 @@
 ---
 name: azure-search-documents
-description: 'Post-regeneration customization guide for azure-search-documents. Verifies _patch.py imports, ApiVersion, enum aliases, mypy/pylint, and changelog after codegen. WHEN: regenerate azure-search-documents; modify azure-search-documents; fix azure-search-documents bug; add azure-search-documents feature; azure-search-documents tsp-client update; edit azure-search-documents _patch.py.'
+description: 'Post-regeneration customization guide for azure-search-documents. Verifies _patch.py imports, ApiVersion, enum aliases, validation, testing, and changelog after codegen. WHEN: regenerate azure-search-documents; azure-search-documents tsp-client update; update azure-search-documents API version; reconcile azure-search-documents _patch.py after regeneration; fix azure-search-documents regeneration break; prepare azure-search-documents release after regeneration.'
 ---
 
 # azure-search-documents — Post-Regeneration Customization Guide
 
 After running `tsp-client update`, the generated code is a raw skeleton — not a shippable SDK. This skill tells you exactly which `_patch.py` files customize it and how to verify those customizations still work after regeneration.
 
-The generator never touches `_patch.py` files, so your customizations survive regeneration. But they import from generated modules that **do** change. A renamed model, a new parameter, or a removed enum value will silently break a `_patch.py` file. The verification steps below catch those breaks.
+The generator never touches `_patch.py` files, so your customizations survive regeneration. Only edit `_patch.py` files for SDK customizations; the sole exception is adding inline `# pylint: disable=` comments to generated files for pylint issues. `_patch.py` files import from generated modules that **do** change, so a renamed model, a new parameter, or a removed enum value can silently break them. The verification steps below catch those breaks.
+
+## Additional references
+
+Use these sidecars for guidance that is required for release-ready changes but does not belong in the generated post-regeneration checklist.
+
+- Release tracks, branch-dependent API surface, and CHANGELOG rules: `references/release.md`
+- Test commands, live recording workflow, and test authoring rules: `references/testing.md`
+
+## Environment setup
+
+Use the alias as a prefix for any command that needs the package environment, for example `venv python`, `venv pip`, `venv azpysdk`, or `venv python -m pytest`. Plain `git`, `grep`, and file commands do not need it.
+
+```powershell
+Set-Alias venv .\.github\skills\azure-search-documents\scripts\Invoke-VenvCommand.ps1
+```
 
 ## Step 1: Run Regeneration
 
@@ -26,14 +41,14 @@ tsp-client update
 
 Every non-empty `_patch.py` imports from generated modules. After regeneration, check those imports still resolve:
 
-```bash
-python -c "from azure.search.documents import SearchClient, SearchIndexingBufferedSender, ApiVersion, DEFAULT_VERSION, IndexDocumentsBatch"
-python -c "from azure.search.documents.aio import SearchClient, SearchIndexingBufferedSender"
-python -c "from azure.search.documents.indexes import SearchIndexClient, SearchIndexerClient"
-python -c "from azure.search.documents.indexes.aio import SearchIndexClient, SearchIndexerClient"
-python -c "from azure.search.documents.indexes.models import SearchField, SearchFieldDataType, SimpleField, SearchableField, ComplexField, KnowledgeBase"
-python -c "from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient"
-python -c "from azure.search.documents.knowledgebases.aio import KnowledgeBaseRetrievalClient"
+```powershell
+venv python -c "from azure.search.documents import SearchClient, SearchIndexingBufferedSender, ApiVersion, DEFAULT_VERSION, IndexDocumentsBatch"
+venv python -c "from azure.search.documents.aio import SearchClient, SearchIndexingBufferedSender"
+venv python -c "from azure.search.documents.indexes import SearchIndexClient, SearchIndexerClient"
+venv python -c "from azure.search.documents.indexes.aio import SearchIndexClient, SearchIndexerClient"
+venv python -c "from azure.search.documents.indexes.models import SearchField, SearchFieldDataType, SimpleField, SearchableField, ComplexField, KnowledgeBase"
+venv python -c "from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient"
+venv python -c "from azure.search.documents.knowledgebases.aio import KnowledgeBaseRetrievalClient"
 ```
 
 If any fail, a generated class/enum was renamed or removed. See `references/customizations.md` for the exact import each `_patch.py` depends on.
@@ -62,7 +77,7 @@ The generator targets the version in `_metadata.json`. The hand-maintained `ApiV
 
 ```bash
 # 1. See what API version the generator used
-python -c "import json; print(json.load(open('_metadata.json'))['apiVersion'])"
+venv python -c "import json; print(json.load(open('_metadata.json'))['apiVersion'])"
 
 # 2. See what versions the SDK currently advertises
 grep -A 20 'class ApiVersion' azure/search/documents/_patch.py
@@ -79,7 +94,7 @@ If the generated API version is **not** in the enum:
 Verify the default round-trips:
 
 ```bash
-python -c "from azure.search.documents._patch import ApiVersion, DEFAULT_VERSION; print(DEFAULT_VERSION.value)"
+venv python -c "from azure.search.documents._patch import ApiVersion, DEFAULT_VERSION; print(DEFAULT_VERSION.value)"
 ```
 
 ## Step 4: Expose New Generated Methods Through `_patch.py`
@@ -109,9 +124,9 @@ For each new method, pick the exposure path:
 
 6. **Re-export via `__all__`** — any NEW symbol you add or override in `_patch.py` MUST be appended to that file's `__all__`. Otherwise `patch_sdk()` will not surface it.
 
-   ```bash
-   python -c "import azure.search.documents as m; print(sorted(m.__all__))"
-   python -c "import azure.search.documents.indexes as m; print(sorted(m.__all__))"
+   ```powershell
+   venv python -c "import azure.search.documents as m; print(sorted(m.__all__))"
+   venv python -c "import azure.search.documents.indexes as m; print(sorted(m.__all__))"
    ```
 
 Every sync wrapper needs a matching async mirror under `aio/`. Shared helpers (`_build_search_request`, `_convert_search_result`, `_convert_index_response`, `_pack_continuation_token`, `_unpack_continuation_token`) live in the **sync** `_operations/_patch.py` and are **imported** by async — do not duplicate them.
@@ -145,29 +160,12 @@ azsdk_package_run_check with checkType="All"
 
 ### CHANGELOG
 
-Open `CHANGELOG.md` and find the topmost `## (Unreleased)` section. Add entries under:
+Follow the CHANGELOG rules in `references/release.md`. Add entries under:
 
 - `### Features Added` — new operations, models, parameters, API version support
 - `### Breaking Changes` — renamed/removed models, changed signatures, dropped API versions
 - `### Bugs Fixed` — fixes to `_patch.py` logic, pagination, encoding, batching
 
-Example:
-
-```markdown
-## 11.x.0bN (Unreleased)
-
-### Features Added
-
-- Added `create_or_update_knowledge_base` to `SearchIndexClient`.
-- Support for API version `2026-05-01-preview`.
-
-### Breaking Changes
-
-- Renamed `OldModel` to `NewModel`.
-```
-
-If no `(Unreleased)` section exists, create one above the latest release using the next version from `azure/search/documents/_version.py`.
-
 ### README
 
 - Add usage examples for new client classes (`KnowledgeBaseRetrievalClient` etc.) or operations.

@@ -0,0 +1,55 @@
+# azure-search-documents - Release and Branching
+
+## Release tracks
+
+Choose the release track before comparing APIs or writing changelog entries:
+
+| Release track | Branch source | Branch name |
+| --- | --- | --- |
+| Preview | Start from `main`, which includes the latest preview API surface. | `search/<api-version>`, for example `search/2026-05-01-preview` |
+| GA | Start from the previous GA branch, not from the latest preview. | `search/<api-version>-ga`, for example `search/2026-05-01-ga` |
+
+## Branch-dependent API surface
+
+Do not assume the latest preview API exists on a GA branch. Method names, resource types, generated models, helper accessors, and package-specific kwargs can differ between branches.
+
+Use method and kwarg inventories in this skill and `customizations.md` as pattern checklists, not as the current branch's source of truth. Before adding, removing, or forwarding a wrapper, verify the current branch's generated operations and `_patch.py` methods. If an example method, accessor, or kwarg does not exist on the current branch, do not add it just to satisfy the checklist.
+
+If the current branch differs from the inventories in many places, consider regenerating the package skill using `.github\skills\create-package-skill\SKILL.md` instead of patching entries one by one.
+
+## CHANGELOG conventions
+
+Use `azsdk_package_update_changelog_content` to draft entries, then review and adjust.
+
+The generated SDK code is the source of truth for CHANGELOG content. If something exists in generated code, treat it as present. Fall back to the TypeSpec config in the spec PR only when the generated code is ambiguous.
+
+After drafting the CHANGELOG, verify both directions:
+
+1. Code to CHANGELOG: for every changed item in generated code, verify it is reflected in `CHANGELOG.md`.
+2. CHANGELOG to code: for every item in `CHANGELOG.md`, verify it matches actual code.
+
+Use the import checks in `SKILL.md` plus targeted `venv python -c "from ... import X; print(X)"` checks for individual symbols.
+
+Sort lists within each CHANGELOG section alphabetically by fully qualified name.
+
+### Preview releases
+
+- `Features Added`: list changes since the previous preview release.
+- `Breaking Changes`: list breaking changes since the previous preview release. Put this beta-only disclaimer before the list:
+
+```markdown
+> These changes do not impact the API of stable versions such as <latest GA version>.
+> Only code written against a beta version such as <latest beta version> may be affected.
+```
+
+### GA releases
+
+- `Features Added`: list changes since the previous GA release. Do not compare against the latest preview.
+- `Breaking Changes`: when both categories apply, group them in this order:
+  1. GA-to-GA breaking changes, with no disclaimer.
+  2. Preview-to-GA breaking changes, after this beta-only disclaimer:
+
+```markdown
+> These changes do not impact the API of stable versions such as <previous GA version>.
+> Only code written against a beta version such as <latest beta of this GA's minor> may be affected.
+```
@@ -1,6 +1,15 @@
 # azure-search-documents — Testing
 
-Tests use `pytest` plus the [Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) for recording and playback. All test files live flat in `tests/`. Always create sync and async versions together.
+Tests use `pytest` plus the [Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) for recording and playback. All test files live flat in `tests/`.
+
+Run commands from `sdk/search/azure-search-documents/` using the `venv` alias from `SKILL.md`:
+
+```powershell
+cd sdk/search/azure-search-documents
+venv python -m pytest tests
+```
+
+Use `python -m pytest` rather than bare `pytest` so tests run with the selected package venv.
 
 ## Unit tests
 
@@ -10,44 +19,54 @@ Pure logic. No HTTP, no recordings, no service needed.
 
 `test_<name>.py` (sync), `test_<name>_async.py` (async).
 
-### Run
+### Run unit tests
 
 ```powershell
 venv python -m pytest tests/ --ignore-glob="*_live*"
 ```
 
 ## Live tests
 
-Make HTTP calls to Azure Search. Runs in playback by default; switch to live mode to record.
+Make HTTP calls to Azure AI Search. Runs in playback by default; switch to live mode to record.
 
 ### File naming
 
 `test_<name>_live.py` (sync), `test_<name>_live_async.py` (async).
 
-### Run — playback
+### Run live tests in playback
 
 Replays existing recordings. Fast, offline.
 
 ```powershell
+$env:AZURE_TEST_RUN_LIVE = "false"
 venv python -m pytest tests/ -k "live"
 ```
 
-### Run — against the real service
-
-Captures new recordings. Required for any new live test.
-
-The [Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) records each HTTP exchange to a separate Azure SDK assets repo. `assets.json` (in the package root) is the pointer: it stores the tag/SHA of the recordings repo this package's tests should replay. Pushing recordings updates that tag.
+### Record live tests
 
-Steps:
+New live tests require new [Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) recordings. Pushing recordings updates the `Tag` in `assets.json`, which points to this package's recordings in `Azure/azure-sdk-assets`.
 
-1. First time: create `scripts\set-live-env.ps1` (gitignored — never commit; it holds endpoints and may hold connection strings) setting `SEARCH_SERVICE_ENDPOINT`, `SEARCH_SERVICE_NAME`, `SEARCH_STORAGE_CONNECTION_STRING`, `SEARCH_STORAGE_CONTAINER_NAME`, and an `az login --tenant <id>` line.
-2. Dot-source: `. .\.github\skills\azure-search-documents\scripts\set-live-env.ps1`
-3. Run with `AZURE_TEST_RUN_LIVE=true`:
+1. Copy `scripts\Set-LiveTestEnvironment.sample.ps1` to `scripts\Set-LiveTestEnvironment.ps1`, fill in local values, and dot-source it:
+   ```powershell
+   . .\.github\skills\azure-search-documents\scripts\Set-LiveTestEnvironment.ps1
+   ```
+2. Run live tests:
    ```powershell
-   $env:AZURE_TEST_RUN_LIVE = "true"
    venv python -m pytest tests/ -k "live"
    ```
+3. Push recordings:
+   ```powershell
+   test-proxy push -a assets.json
+   ```
+4. Keep the updated `assets.json` with your changes.
+
+## Adding new tests
+
+This checklist is mandatory for every test change. Do not add or update tests without checking each item below.
 
-> All `venv` invocations in this file assume the alias is set as shown in `SKILL.md → Environment Setup`. Run from the package root.
-4. Push recordings: `test-proxy push -a assets.json` (updates the SHA stored in `assets.json`).
-5. Include the updated `assets.json` in your PR.
+1. Start from current SDK source. Prioritize public behavior owned or customized by the Python SDK, especially `_patch.py` and other hand-written code paths.
+2. Prefer unit tests whenever the behavior is SDK-owned and can be proven without HTTP. Use playback or live tests only when the service contract matters.
+3. Place each test in the file that matches the public SDK surface and subject that owns the final assertion: unit `test_<surface_or_helper>.py`, async unit `test_<surface_or_helper>_async.py`, live `test_<public_surface>_<subject_family>_live.py`, async live `test_<public_surface>_<subject_family>_live_async.py`.
+4. Name each test after the primary public SDK method or surface under test: `test_<method_or_surface>_<scenario_or_behavior>`. If a parametrized test covers a family of related methods, use a clear family name instead of listing every method.
+5. Use deterministic fixtures in Python builders. Share repeated setup and keep scenario-specific setup in the test.
+6. Add sync and async together when both public surfaces exist, with matching test names unless the public API differs.
@@ -0,0 +1 @@
+Set-LiveTestEnvironment.ps1
@@ -4,13 +4,13 @@
     activation state required. Aborts if the .venv is missing.
 
 .EXAMPLE
-    .\.github\skills\azure-search-documents\scripts\run-in-venv.ps1 azpysdk pylint .
-    .\.github\skills\azure-search-documents\scripts\run-in-venv.ps1 python -m pytest tests\
-    .\.github\skills\azure-search-documents\scripts\run-in-venv.ps1 pip list
+    .\.github\skills\azure-search-documents\scripts\Invoke-VenvCommand.ps1 azpysdk pylint .
+    .\.github\skills\azure-search-documents\scripts\Invoke-VenvCommand.ps1 python -m pytest tests\
+    .\.github\skills\azure-search-documents\scripts\Invoke-VenvCommand.ps1 pip list
 #>
 
 if ($args.Count -eq 0) {
-    Write-Error "Usage: run-in-venv.ps1 <command> [args...]"
+    Write-Error "Usage: Invoke-VenvCommand.ps1 <command> [args...]"
     exit 2
 }
 
@@ -23,7 +23,8 @@ FATAL: .venv missing at $pkgRoot\.venv.
 Bootstrap it with:
     cd $pkgRoot
     python -m venv .venv
-    .\.venv\Scripts\python -m pip install -e .[dev]
+    .\.venv\Scripts\python -m pip install -r dev_requirements.txt
+    .\.venv\Scripts\python -m pip install -e .
 Then retry.
 "@
     exit 1

@@ -0,0 +1,20 @@
+<#
+.SYNOPSIS
+    Sample local environment setup for azure-search-documents live tests.
+
+.DESCRIPTION
+    Copy this file to Set-LiveTestEnvironment.ps1 and replace placeholders with
+    local values. Do not commit Set-LiveTestEnvironment.ps1 because it may
+    contain secrets.
+#>
+
+$env:SEARCH_SERVICE_ENDPOINT = "https://<search-service-name>.search.windows.net"
+$env:SEARCH_SERVICE_NAME = "<search-service-name>"
+$env:SEARCH_STORAGE_CONNECTION_STRING = "<storage-connection-string>"
+$env:SEARCH_STORAGE_CONTAINER_NAME = "<storage-container-name>"
+
+# Uncomment when recording live tests.
+# $env:AZURE_TEST_RUN_LIVE = "true"
+
+# Uncomment if you need to authenticate before live tests.
+# az login --tenant "<tenant-id>"