microsoft / microsoft/typespec
Versioning of documentation updates to avoid unintended updates to `data-plane` files
- 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
Assessment
This issue has not been assessed yet.