Skip to content

[Search] Add samples authoring reference to azure-search-documents skill #47689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hizixin wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Search] Add samples authoring reference to azure-search-documents skill #47689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Use these sidecars for guidance that is required for release-ready changes but d

- Release tracks, branch-dependent API surface, and CHANGELOG rules: `references/release.md`
- Test commands, live recording workflow, and test authoring rules: `references/testing.md`
- Sample authoring workflow, `.http` contract parity, and live-run setup: `references/samples.md`

## Environment setup

Expand Down
20 changes: 20 additions & 0 deletions ...re-search-documents/.github/skills/azure-search-documents/references/samples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# azure-search-documents samples

Samples run live against a search service. Create `Set-LiveSampleEnvironment.ps1` from the release resources to set the env vars the samples read, keeping secrets out of it. Run commands from `sdk/search/azure-search-documents/` using the `venv` alias from `SKILL.md`:

```powershell
cd sdk/search/azure-search-documents
. .\.github\skills\azure-search-documents\scripts\Set-LiveSampleEnvironment.ps1
venv python samples/sample_knowledge_source_file_preview.py
```

## Adding new samples

This checklist is mandatory for every sample change. Do not add or update samples without checking each item below.

1. Gather the three release inputs first: the sample requirements, `.http` calls, and the resources to run against. Ask before editing if any is missing or ambiguous.
2. Name the file after the scenario from the requirements: `sample_<scenario>[_preview][_async].py`.
3. Build the file body: a DESCRIPTION/USAGE docstring, `run_tag`-based resource names so reruns don't collide, and the demonstrated calls and their SDK imports wrapped in `# [START <name>]` / `# [END <name>]` tags with id = file name.
4. Mirror each scenario's `.http` calls as the source of truth for the SDK flow: same operations (one SDK method per verb + route), call order, parameters, body fields, headers, and options, using SDK models instead of raw JSON; only swap in hotel data. If a starter value fails live, change only that value, not the call shape.
5. Keep the full SDK flow visible inside the tags, down to credential and client construction; push setup and cleanup into `sample_utils.py` helpers. Helper-only data may use compact dicts; the demonstrated scenario may not.
6. Mirror each sync sample in async; only async clients, `async with`, `await`, iteration, and cleanup differ.
Loading