OpenParable
Skip to content
← Back to skills

Search Documents Version Diff

Testing & Quality
search-documents-version-diff

Search Documents Version Diff is an Agent Skill for testing & quality published in the Azure/azure-sdk-for-net repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Diff the current Azure.Search.Documents public API surface against a previous published version and detect preview-to-preview regressions where the SDK customization layer was not bubbled up after a TypeSpec change. Use whenever the user asks to compare Azure.Search.Documents betas, verify no Azure.Search.Documents preview features dropped, regression audit between Azure.Search.Documents versions, sanity-check a release branch for Azure.Search.Documents, or investigate a missing Azure.Search.Documents preview feature — even if they don't say the word "diff". Specifically catches dropped wrappers (QueryAnswer/QueryCaption/QueryRewrites style), lost SearchOptions aggregator redirectors, `@@access("internal")` flips, deleted-instead-of-gated `#if AZURE_SEARCH_PREVIEW` blocks, dropped `ServiceVersion` enum values, and convenience-to-protocol downgrades.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Azure/azure-sdk-for-net/blob/HEAD/sdk/search/Azure.Search.Documents/.github/skills/search-documents-version-diff/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/search-documents-version-diff, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Azure.Search.Documents — Version Diff

PropertyValue
PackageAzure.Search.Documents
Rootsdk/search/Azure.Search.Documents/
Public API listingapi/Azure.Search.Documents.netstandard2.0.cs
TypeSpec pintsp-location.yaml (commit:)

When to use

The Azure.Search.Documents SDK ships a hand-customized layer over generated code. When a new TypeSpec or client.tsp lands, regen can silently drop a previously-shipped public API because the customization wasn't reapplied. A plain git diff will not surface this — you need to compare the shipped public surface, then classify each removal against what the current spec and generated code still contain.

Use this skill to produce that classified diff. Do not use it for:

Inputs

InputSource
Previous version referenceGit tag (Azure.Search.Documents_<version>), branch, commit SHA, or local .nupkg
Current API listingapi/Azure.Search.Documents.netstandard2.0.cs (working tree)
Both TypeSpec commitstsp-location.yaml on each side (auto-resolved by the script)
Both channel labels<Version> in each Azure.Search.Documents.csproj — preview iff contains beta (auto)

If the user does not specify a previous reference, list the most recent tags and ask. Do not silently default to origin/main — it leads to nonsense diffs when main already contains the current branch.

git tag --list 'Azure.Search.Documents_*' --sort=-creatordate | Select-Object -First 10

Workflow

1. Resolve baselines and run the diff script

The deterministic work — git-fetching both sides, parsing types/members, computing added/removed/changed buckets — lives in scripts/Compare-ApiSurface.ps1. Run it first, then operate on the JSON it produces.

./scripts/Compare-ApiSurface.ps1 -PreviousRef Azure.Search.Documents_<version>
# default output: sdk/search/Azure.Search.Documents/artifacts/search-version-diff.json

The JSON includes: previous/current metadata (version, channel, tspCommit), comparisonMode (preview->preview etc.), and addedTypes / removedTypes / changedTypes / addedMembers / removedMembers arrays.

Non-obvious: if the previous side is a .nupkg, the script throws. Extract lib/netstandard2.0/Azure.Search.Documents.dll, decompile to a single .cs listing with Microsoft.CodeAnalysis or ildasm, commit it to a local throwaway branch, and pass that branch as -PreviousRef. Do not paper over a missing baseline by pointing at origin/main.

2. Pick the comparison mode

Read comparisonMode from the JSON. It controls how aggressively to flag removals:

ModeRemoval interpretation
preview->previewPrimary focus. Removals are likely regressions unless the spec also removed the feature.
GA->previewRemovals usually intentional shedding before GA. Flag as By design unless the user disputes.
preview->GARemovals expected (preview-only features did not promote). Flag as By design.
GA->GAAny removal is a Critical breaking change. Stop and surface immediately.

3. Classify each removed/changed symbol

For every entry in removedMembers, removedTypes, and changedTypes, pick a pattern from references/heuristics.md. That file defines seven named patterns (P1–P7) with signals and fix locations, plus a decision aid at the bottom.

Non-obvious step: classifying correctly requires looking at the current TypeSpec at its pinned commit — not the spec checked out locally, which may be on a different SHA than tsp-location.yaml. Fetch raw via:

$sha = ((Get-Content tsp-location.yaml | Select-String '^commit:').Line -replace '^commit:\s*','').Trim()
Invoke-RestMethod "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/$sha/specification/search/Search.Service/client.tsp"

Also search src/Generated/Models/ locally — many "removed" public symbols still exist there as internal (pattern P3) or as *Raw siblings (pattern P1). If the heuristic decision aid can't place an item, leave it as P7 — do not guess.

4. Write the report

Write a single Markdown file to artifacts/search-version-diff.md. Use exactly this structure so reviewers can navigate by header:

# Azure.Search.Documents — Version Diff Report

| | Previous | Current |
|---|---|---|
| Version | <prev-version> | <current-version> |
| Channel | <preview|GA> | <preview|GA> |
| TypeSpec SHA | <prev-sha> | <current-sha> |
| Comparison mode | <preview->preview|...> | |

## Summary
- Removed: <N> types, <M> members
- Added: <N> types, <M> members
- Changed: <N> types
- **Regressions (action required): <N>**

## Regressions (action required)
| Symbol | Scope | Pattern | Evidence | Fix location |
|---|---|---|---|---|
| `SemanticSearchOptions.QueryRewrites` | Property | P1 — wrapper dropped | `QueryRewritesRaw` still in `src/Generated/Models/SemanticSearchOptions.cs` | `src/Models/SemanticSearchOptions.cs` partial, gated `#if AZURE_SEARCH_PREVIEW` |

## By-design drops
Items the spec intentionally removed (preview shedding into GA, or `@@access("internal")` confirmed intentional). No action.

## Renamed / Changed
Old → new, with the rename source (`@@clientName`, `[CodeGenMember]`, manual partial class).

## Added (informational)
Bullet list of new public symbols. No action.

## Open questions (P7)
Items the heuristics could not classify. Flag for human review.

In chat, echo only the Summary and Regressions sections. Everything else stays in the file.

5. Stop conditions

  • If the previous baseline cannot be resolved → stop, ask the user. Do not fall back.
  • If comparisonMode == GA->GA and any member is removed → stop and surface to the user immediately; this is release-blocking.
  • If more than ~20 items land in P7 → the heuristics are stale for this regen. Surface a few examples to the user and ask whether to extend references/heuristics.md before continuing.

Output

  • File: sdk/search/Azure.Search.Documents/artifacts/search-version-diff.md
  • Chat: Summary table + Regressions table only.

Related skills