non-breaking-versioning

Id

@azure-tools/typespec-azure-core/non-breaking-versioning

Check that only backward compatible versioning change are done to a service.

Verify that only backward compatible changes are made to the API.

Impact

• Area: API, SDK

Flags versioning changes that would break existing clients across api-versions.

❌ Incorrect

• Removed

model Foo {
  @removed(Versions.v2024_01_01)
  bar: string;
}

• Renamed

model Foo {
  @renamedFrom(Versions.v2024_01_01, "baz")
  bar: string;
}

• Added required property

model Foo {
  @added(Versions.v2024_01_01)
  bar: string;
}

• Made optional without default

model Foo {
  @madeOptional(Versions.v2024_01_01)
  bar: string;
}

✅ Correct

• Adding new type

@added(Versions.v2024_01_01)
model Foo {}

• Adding operation

@added(Versions.v2024_01_01)
op foo(): Foo;

• Adding optional property

model Foo {
  @added(Versions.v2024_01_01)
  bar?: string;
}

• Made optional with default

model Foo {
  @madeOptional(Versions.v2024_01_01)
  bar?: string = "default";
}

Suppression

Suppress only when the break is intentional and unavoidable; otherwise model the change in a non-breaking way.