diff --git a/docs/release-notes/release-2023-07-11.md b/docs/release-notes/release-2023-07-11.md new file mode 100644 index 0000000000..f59cd4be2d --- /dev/null +++ b/docs/release-notes/release-2023-07-11.md @@ -0,0 +1,92 @@ +--- +title: July 2023 +--- + +# Release Notes July 2023 (2023-07-11) + +:::danger +This release contains **breaking changes** +::: + +## New Features + +### `@typespec/compiler` and core language + +- New built-in linter system. Typespec libraries are able to define linting rules which can be configured in `tspconfig.yaml`. See documentation for [configuring a linter](https://microsoft.github.io/typespec/introduction/configuration#linter---configuring-linters) and [writing a linter](https://microsoft.github.io/typespec/extending-typespec/linters) +- Allow decorators, directives and doc comments to be specified in any order +- Format doc comments above decorators and directives +- Improve formatting for properties with comments and decorators +- Support for new Unicode 15.0 identifier characters + +### Emitter framework + +- Add `writeOutput` to TypeEmitter for additional customization in writing generated files +- Add `meta` property to source files and declarations to store arbitrary metadata +- Add support for emitting enum member references +- Add new `TypeEmitter` methods for scalar instantiation + +### `@typespec/http` library + +- Add documentation on automatic header name resolution from property name for `@header` decorator + +### `@typespec/json-schema` emitter + +- Support `@extension` for adding arbitrary vendor extensions into the output +- Add support for `Record` +- Support templates instantiated with intrinsic types and type expressions +- Export emitter and related types from the npm package +- By default, types that are not marked with `@jsonSchema` or are within a namespace with `@jsonSchema` are bundled into the schemas that reference them. Set the `emitAllRefs` option to true to get the previous behavior of emitting all types referenced as JSON Schema + +### `@typespec/openapi3` emitter + +- Omit `x-typespec-name` extension by default from openapi3 output. A new configuration and command line option `include-x-typespec-name: \"inline-only\" | \"never\"` has been added to get previous behavior + +### `@typespec/rest` library + +- Add `isListOperation` function migrated from `@typespec/compiler` + +## Bug Fixes + +### `@typespec/compiler` and core language bug fixes + +- Add support for `UTF-8 with bom` for other files loaded by typespec compiler. `.tsp` files already had support, this make it more available for any library/emitter using the compiler api to load a file. +- Fix signature help after comment with no closing parenthesis or angle bracket +- Doc comment `/** */` should override base type doc in `model is` or `op is` +- Formatter incorrectly formatting `::` to `.` +- Fix formatting issue with comment between decorator and scalar or interface +- Fix stack overflow when a circular reference with `op is` exists inside an interface. +- Clean up handling of non-standard entrypoints in language server +- Fix stack overflow when referencing decorator target in checker and projections + +### `@typespec/openapi3` emitter bug fixes + +- OpenAPI emitters: treat union namespaces like namespaces for other types + +### Emitter framework bug fixes + +- Fix that some context methods were not being passed the expected parameters +- Fix that context was set incorrectly for some `TypeEmitter` methods, and add missing context methods for model properties, enum members, and union variants + +### `@typespec/json-schema` emitter bug fixes + +- Fix a bug that could result in a schema being bundled more than once + +## Breaking Changes + +### For Specification Authors + +- Update tsp init template schema for future extensibility. Older tsp version will fail validation when trying to initialize a project with a new template definition. +- Json Schema Emitter: the namespace has been corrected to TypeSpec.JsonSchema. Update any using statements from `JsonSchema` to `TypeSpec.JsonSchema`, and any references from `JsonSchema.[Type]` to `TypeSpec.JsonSchema.[Type]`. + +### For Emitters and Libraries + +- Minimum version of TypeScript updated to 5.0. TypeSpec is using new features available in TypeScript 5.0 which result in a definition file not parsable by older version. Note that this only affect compiling TypeScript code and is not breaking any JS or TypeSpec code. [See more information on typescript 5.0](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/) +- Emitter Framework: Add support for templates instantiated with types without declared names. In such cases, `TypeEmitter`'s declarationName method may return `undefined`, and so the various `*Instantiation` methods might be called with an undefined name, and `AssetEmitter`'s `emitDeclarationName` method might return undefined. +- Make internal `@resourceTypeForKeyParam` decorator in `@typespec/rest` library private + +## Deprecations + +- `@list` decorator from TypeSpec core is deprecated. Use `@listsResource` from `@typespec/http` instead +- `isListOperation` function from TypeSpec core is deprecated. Use `isListOperation` from `@typespec/http` instead +- `getListOperationType` from TypeSpec core is deprecated +- `@typespec/linter` Package is deprecated in favor of built-in linter system