Azure · idickerson7 · Mar 19, 2026
@@ -0,0 +1,120 @@
+---
+name: Azure.Search.Documents
+description: "**WORKFLOW SKILL** — Orchestrate the full release cycle for azure-search-documents Java SDK including TypeSpec generation, customization fixes, testing, and versioning. WHEN: \"search SDK release\", \"regenerate search SDK\", \"update search API version\", \"fix search customization errors\", \"search pre-release validation\". FOR SINGLE OPERATIONS: Use Maven commands directly for one-off builds or generation."
+---
+
+# azure-search-documents — Package Skill (Java)
+
+## When to Use This Skill
+
+Activate when user wants to:
+- Prepare a new GA or preview release of azure-search-documents
+- Update to a new API spec version (new commit SHA)
+- Regenerate SDK from TypeSpec and fix customization errors
+- Run pre-release validation (build, test)
+- Understand the SDK architecture or customization patterns
+
+## Prerequisites
+
+- Read [references/architecture.md](references/architecture.md) — source layout, generated vs. custom split, package map, service version rules
+- Read [references/customizations.md](references/customizations.md) — JavaParser AST patterns, `SearchCustomizations.java`, backward-compat retention
+
+## Steps
+
+### Phase 0 — Determine Scope
+
+Ask the user:
+1. New API version or re-generation of current spec?
+2. GA release or beta/preview release?
+3. Target release date (for changelog)?
+
+If new API version: get the new spec **commit SHA** and **API version string** (e.g., `2026-04-01`).
+
+> **STOP** if the user cannot provide the commit SHA — do not guess or use HEAD.
+
+### Phase 1 — Update `tsp-location.yaml`
+
+*(Skip if commit SHA is not changing)*
+
+Set `commit` to the new SHA in `sdk/search/azure-search-documents/tsp-location.yaml`. Leave other fields unchanged.
+
+### Phase 2 — Generate SDK from TypeSpec
+
+Run code generation:
+```powershell
+tsp-client update
+```
+
+### Phase 3 — Build and Fix Customizations
+
+1. Run `mvn clean compile -f sdk/search/azure-search-documents/pom.xml`
+2. Check [references/architecture.md](references/architecture.md) and [references/customizations.md](references/customizations.md) for error patterns and fix guidance.
+3. Prefer model renames, property renames, model visibility changes, and type changes directly updated in TypeSpec `client.tsp` rather than in SDK code. Inform user of any such patterns detected in code and recommend TypeSpec update for better long-term maintenance.
+4. If customization errors occur, update `customizations/src/main/java/SearchCustomizations.java` — see customizations reference for patterns.
+
+**Gate:** Clean build — zero errors from `mvn clean compile`.
+
+### Phase 3.5 — Update Service Version
+
+`SearchServiceVersion.java` is generated by TypeSpec but customized by `SearchCustomizations.java`. Two things must stay in sync:
+
+1. **`SearchCustomizations.includeOldApiVersions()`** — add the previous latest version to the list of old versions
+2. **`SearchServiceVersion.getLatest()`** — verify it returns the new version (this is handled by the generator)
+
+For example, if moving from `2025-09-01` to `2026-04-01`:
+- The generator produces the `V2026_04_01` constant and `getLatest()` returning it
+- Add `"2025-09-01"` to the version list in `includeOldApiVersions()` if not already present
+
+**Gate:** `SearchServiceVersion` enum contains all required versions, `getLatest()` returns the new version.
+
+### Phase 4 — Run Tests
+
+1. Run `mvn test -f sdk/search/azure-search-documents/pom.xml`
+2. Live tests only if provisioned service is available (requires environment variables).
+
+**Gate:** All non-live tests pass.
+
+### Phase 5 — Update Changelog
+
+Fill "Features Added", "Breaking Changes", "Bugs Fixed", "Other Changes" in `CHANGELOG.md` from generated code and API diffs. Write from the user's perspective.
+
+### Phase 6 — Update Version
+
+Update version in `pom.xml` following the `{x-version-update}` marker convention:
+- GA: `X.Y.Z`
+- Beta: `X.Y.Z-beta.N`
+
+```xml
+<version>12.0.0-beta.1</version> <!-- {x-version-update;com.azure:azure-search-documents;current} -->
+```
+
+### Phase 7 — Final Validation
+
+Re-run any step whose outputs changed:
+
+- [ ] `mvn clean compile` if `src/` or `customizations/` changed since Phase 3
+- [ ] `mvn test` if any source changed since Phase 4
+- [ ] Verify `CHANGELOG.md` entry is complete
+
+**Gate:** Clean build, all non-live tests pass.
+
+## Execution Order Summary
+
+| Phase | Action | Gate |
+|-------|--------|------|
+| 0 | Determine scope and release type | User provides commit SHA |
+| 1 | Update `tsp-location.yaml` | — |
+| 2 | Generate SDK (`tsp-client update`) | — |
+| 3 | Build and fix errors (`mvn clean compile`) | Zero errors |
+| 3.5 | Update `SearchServiceVersion` via `SearchCustomizations.java` | All versions present, `getLatest()` correct |
+| 4 | Run tests (`mvn test`) | All non-live tests pass |
+| 5 | Update changelog | All changes documented |
+| 6 | Bump version in `pom.xml` | — |
+| 7 | Final validation | Clean build + tests |
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/architecture.md](references/architecture.md) | Source layout, generated vs. custom split, package map, service version rules |
+| [references/customizations.md](references/customizations.md) | JavaParser AST patterns, `SearchCustomizations.java`, backward-compat retention |