Skip to content

docs: add versioning guidance for spread-in properties using augment decorators - #5324

Draft
Mark Cowlishaw (markcowl) with Copilot wants to merge 3 commits into
mainfrom
copilot/cover-version-scoping-spread-model-property
Draft

docs: add versioning guidance for spread-in properties using augment decorators#5324
Mark Cowlishaw (markcowl) with Copilot wants to merge 3 commits into
mainfrom
copilot/cover-version-scoping-spread-model-property

Conversation

Copilot AI commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

The versioning docs cover @added/@removed on inline-declared properties but not on properties introduced via model spreads (...SomeModel), which have no inline declaration site for decorators. This gap causes authors to either leave spread properties unscoped (breaking the API surface of earlier versions) or attempt workarounds that don't compile.

Adds a new subsection under "Complex Scenarios" in the Evolving APIs versioning doc covering:

  • Why augment decorators are required — spread-in members have no inline site for @added/@removed; the @@ augment form must be used instead
  • @@added example — scoping a ManagedServiceIdentityProperty spread to a specific version
  • @@removed example — removing a spread-in property in a later version
  • Applicability note — same pattern works for @@madeOptional, @@madeRequired, @@renamedFrom, @@typeChangedFrom
model Employee is TrackedResource<EmployeeProperties> {
  ...ResourceNameParameter<Employee>;
  ...ManagedServiceIdentityProperty;
}

// Introduce the spread-in 'identity' property starting in v2 only.
@@added(Employee.identity, Versions.v2);

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

…decorators

Closes #4809

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the meta:website TypeSpec.io updates label Aug 26, 2026
Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
Copilot AI changed the title [WIP] Add documentation for version-scoping a spread model property with @@added docs: add versioning guidance for spread-in properties using augment decorators Aug 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

meta:website TypeSpec.io updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TypeSpec Authoring Docs: cover version-scoping a spread model property with @@added

2 participants