azure/azure-sdk-for-java/azure-search-documents

azure-search-documents -- Package Skill

The generate-sdk-locally shared skill handles generation, build, test, and customization workflows -- including running azsdk_customized_code_update when builds fail. This skill activates after those tools have been tried. It covers what they can't solve: search-specific error diagnosis, customization fragility patterns, and convenience layer design.

Common Pitfalls

• Never hand-edit generated files. Files with // Code generated by Microsoft (R) TypeSpec Code Generator. are overwritten on every tsp-client update. All modifications go through SearchCustomizations.java.
• Check `SearchCustomizations.java` FIRST when generated files have errors. The customizations run during generation and can produce broken output if the generated code structure changed. The most common culprits:
• hideWithResponseBinaryDataApis() -- rewires method bodies across packages, can create cross-package import mismatches
• includeOldApiVersions() -- can duplicate enum constants the generator now produces
• addSearchAudienceScopeHandling() -- may fail if builder structure changed
• Methods without `@Generated` in generated files are hand-written. These are convenience wrappers that the generator preserves but does NOT update. After regeneration, you must manually update them to match any changed generated signatures. Look at how the @Generated methods in the same file were updated as a pattern to follow.
• `includeOldApiVersions` can create duplicate enum constants. If the generator starts producing a version that was previously only in the customization list, you get a compilation error. Remove the version from the customization list.

After Regeneration -- Diagnose and Fix Build Errors

Categorize each compilation error:

Verify Service Version

SearchServiceVersion.java is generated but customized by SearchCustomizations.java.

1. Check getLatest() returns the new version
2. In includeOldApiVersions():

• Remove any version the generator now produces (prevents duplicates)
• Add the previous latest version if not already produced by the generator

1. Verify all expected old versions are present

Detect Breaking Changes

# Removed/renamed public types
git diff --name-status HEAD -- sdk/search/azure-search-documents/src/main/java/ | grep "^D"

Watch for: removed types, renamed constants (need @Deprecated aliases), changed property types, removed method overloads.

Test Recording Notes

If test recordings are stale, update assets.json and re-record. Remove tests for features that no longer exist in the API.

References