microsoft / microsoft/typespec

Versioning of documentation updates to avoid unintended updates to `data-plane` files

Open
#4,972 0 comments 0 reactions 0 assignees View on GitHub
feature lib:versioning triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

## What is this about

While working on the [Azure OpenAI TypeSpec definition](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices/OpenAI.Inference), sometimes we need to update the documentation of fields and models. Doing so, retroactively updates the documentation in the OpenAPI v2 generated files in the associated `data-plane` subfolder.

To keep old spec versions' documentation in the same state as when it was written, it would be useful to be able to specify with a decorator or in a different way, up to which version this documentation is still valid.

## Example

Let's say for instance, we have a model that looks like this:

```ts
/**
* My model documentation
*/
model Foo {
/** Bar field */
bar: string
// ...
}
```

Which gets updated to:

```ts
/**
* My model documentation
*/
model Foo {
/** Bar field. This field is facing deprecation and won't be available as of January 2025. */
bar: string;

/** Baz field. Replacement of Bar field. */
baz: BazModel;
// ...
}
```

In this example, we would have to have a 2nd update to the documentation of `baz` removing the `"Replacement of Bar field."` bit of the doc. But being able to update docs like this, would enable us to provide better guidance to our customers on the usage of our SDKs.

Whenever we reach the point when the field needs to be removed, we will use the appropriate decorator `@removed(ServiceVersions.some_version)` (or `@TypeChangedFrom`) but it would be good be able to notify users about the deprecation ahead of time by updating the documentation without affecting our documentation history in the `data-plane` folder.

Additionally, these documentation changes often times come from OpenAI as an upstream dependency update. A concrete recent example of this can be found for the `maxToken` field affected by this [PR](https://github.com/Azure/azure-rest-api-specs/pull/30909/files#diff-cbaf8c2d949207545c41bafb94afe6c9682f5e1379b27198885bc8eff548b9bbR121-R126).

## Proposal

Making `@doc` accept a version parameter, or introducing a new decorator into the [versioning decorator suite](https://typespec.io/docs/libraries/versioning/reference/decorators/) along the lines of `@docLastUpdated(ServiceVersions.some_version)` could signal emitters, particularly in the case of emitting OpenAPI files in the `data-plane` folder, to ignore the documentation value update up to the service version provided in the parameter of the decorator.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.