Azure / Azure/azure-sdk-tools

[TypeSpec] Improve client customizations instructions

Open
#12,420 0 comments 0 reactions 0 assignees View on GitHub
needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
143

Description

Currently in the azure-rest-api-specs repo, there are copilot instructions to reference the llms.txt files generated for typespec and typespec-azure docs.

In testing applying client customizations to specs, I'm finding that while copilot will reference the correct docs, it doesn't always use the typespec azure libraries correctly.

For example, I prompted copilot to split a service into 2 clients for only the python SDK, and specified which operations belonged to which client. It correctly used the `@client` decorator, but it never applied scoping correctly.

Now, if I asked copilot a follow-up along the lines of "How are you sure this only applies to python", it again looks up the documentation and correctly identifies it needs to use the scopes parameter, but I can't get it to do that on its own proactively.

We should look into either updating the typespec-azure docs to put more emphasis on when each parameter should be used/give more examples, and/or update instructions to provide more guidance on patterns to look for (e.g. scope) when applying customizations.

Contributor guide

Open the contributing guide

Research direction

Review the existing Copilot instructions and the TypeSpec and TypeSpec Azure documentation referenced through the generated llms.txt files. Compare the client customization guidance with the reported Python-only client scenario, focusing on when parameters such as scope should be used. Done means the relevant documentation or instructions provide clearer parameter guidance and representative examples.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.