Azure / Azure/azure-sdk-tools

[TypeSpec Authoring] Assess TypeSpec semantic intent

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

Description

## Goal

Assess changed TypeSpec code and explain its semantic intent: the API behavior the author is trying to introduce or change, rather than only restating the syntax diff.

Each intent should be concise, supported by the changed TypeSpec source, and avoid unsupported assumptions.

## Example

[TypeSpec source](https://github.com/Azure/azure-sdk-tools/blob/main/.github/skills/azure-typespec-author/evaluate/fixtures/001005-version-add-preview-after-preview/employee.tsp#L23-L29)

```typespec
@removed(Versions.v2024_10_01_preview)
@renamedFrom(Versions.v2024_10_01_preview, "age")
oldAge?: int32;

@added(Versions.v2024_10_01_preview)
age?: int32 = 21;
```

**Semantic intent:** Add a default value of `21` to the existing `age` property in a new API version. The combined add, rename, and remove decorators model the old and new forms across the version boundary while preserving the wire name `age`.

## Acceptance criteria

- Identify the main semantic intents in a TypeSpec change.
- Link each intent to the relevant TypeSpec source.
- Clearly mark uncertainty when the intent cannot be established from the code.

Contributor guide

Open the contributing guide

Research direction

Start with the linked employee.tsp example and the stated acceptance criteria. Define how changed TypeSpec source is mapped to concise semantic intents, with links to relevant source and explicit uncertainty; done when the main intents in a change are identified without unsupported assumptions.

Written by the indexing model from the issue text.

Assessment

Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.