microsoft · timotheeguerin · Feb 18, 2025 · Feb 28, 2025 · Feb 28, 2025 · Feb 28, 2025
@@ -53,6 +53,7 @@ const sidebar: SidebarItem[] = [
       "handbook/style-guide",
       "handbook/formatter",
       "handbook/reproducibility",
+      "handbook/breaking-change-policy",
       {
         label: "Configuration",
         items: ["handbook/configuration/configuration", "handbook/configuration/tracing"],

@@ -0,0 +1,56 @@
+---
+title: Breaking Change Policy
+---
+
+# Breaking Change Policy
+
+import { Badge } from "@astrojs/starlight/components";
+
+:::note
+This is to be applicable after 1.0.0 release
-This is to be applicable after 1.0.0 release
+The information in this document is applicable to TypeSpec packages with version 1.0.0 or greater.
-This is to be applicable after 1.0.0 release
+The information in this document is applicable to TypeSpec packages with version 1.0.0 or greater.
+:::
+
+## Versioning Scheme
+
+TypeSpec Compiler and libraries follow [semver](https://semver.org/) for versioning. Which means a breaking change(according the following policy) will only be introduced in a major version release.
+
+## Breaking Change Philosophy
+
+The basic of the policy can be summarized as follows: existing language syntax and semantics will not change without a major version. The runtime behavior for a given TypeSpec will not change without a major version. TypeSpecs leveraging new or updated features may cause runtime API consumers to fail (e.g. because a new type is unhandled) or builds to fail (e.g. because exhaustive unions are no longer exhaustive).
-The basic of the policy can be summarized as follows: existing language syntax and semantics will not change without a major version. The runtime behavior for a given TypeSpec will not change without a major version. TypeSpecs leveraging new or updated features may cause runtime API consumers to fail (e.g. because a new type is unhandled) or builds to fail (e.g. because exhaustive unions are no longer exhaustive).
+Existing language syntax and semantics will not change without a major version. The runtime behavior for a given TypeSpec will not change without a major version. TypeSpecs leveraging new or updated features may cause runtime API consumers to fail (e.g. because a new type is unhandled in an emitter or library that it uses) or builds to fail (e.g. because exhaustive unions are no longer exhaustive).
-The basic of the policy can be summarized as follows: existing language syntax and semantics will not change without a major version. The runtime behavior for a given TypeSpec will not change without a major version. TypeSpecs leveraging new or updated features may cause runtime API consumers to fail (e.g. because a new type is unhandled) or builds to fail (e.g. because exhaustive unions are no longer exhaustive).
+Existing language syntax and semantics will not change without a major version. The runtime behavior for a given TypeSpec will not change without a major version. TypeSpecs leveraging new or updated features may cause runtime API consumers to fail (e.g. because a new type is unhandled in an emitter or library that it uses) or builds to fail (e.g. because exhaustive unions are no longer exhaustive).
+``
+
+- The language syntax and semantics for existing language elements will not change within a major version.
+- A spec that was building successfully should build successfully with the new version of the compiler and libraries with the same major version.
- A spec that was building successfully should build successfully with the new version of the compiler and libraries with the same major version.
+- A spec that builds successfully with a version of the TypeSpec compiler and its libraries will build successfully with a newer version of the compiler and libraries within the same major version.
- A spec that was building successfully should build successfully with the new version of the compiler and libraries with the same major version.
+- A spec that builds successfully with a version of the TypeSpec compiler and its libraries will build successfully with a newer version of the compiler and libraries within the same major version.
+- New types and functionalities can be added in a minor version release.
+  - If a spec updates to use that new functionality/type it is not considered a breaking change if it goes through a library/emitter that will now break.
+- TypeScript types might change in ways that introduce compilation type checking errors. Those are not considered breaking changes.
- New types and functionalities can be added in a minor version release.
-  - If a spec updates to use that new functionality/type it is not considered a breaking change if it goes through a library/emitter that will now break.
- TypeScript types might change in ways that introduce compilation type checking errors. Those are not considered breaking changes.
+- New types and functionality may be added in a minor version release to the compiler or any TypeSpec library.
+  - If a spec uses the new type or functionality, existing libraries or emitters may not work with it, and this is not considered a breaking change in the compiler or library that introduced the type. Spec authors should expect that _existing_ specs will continue to work with their workflows, but not that newly-added features will work with their existing workflows every time.
+- TypeScript API types in TypeScript might change in ways that introduce TypeScript type checking errors (e.g. adding a new variant to a union). TypeScript type checking errors in library builds are not considered breaking changes, and library authors working in TypeScript should take care to program defensively as appropriate. More information about TypeScript API guarantees is provided in the section _Categories of Breaking Changes_ below.
- New types and functionalities can be added in a minor version release.
-  - If a spec updates to use that new functionality/type it is not considered a breaking change if it goes through a library/emitter that will now break.
- TypeScript types might change in ways that introduce compilation type checking errors. Those are not considered breaking changes.
+- New types and functionality may be added in a minor version release to the compiler or any TypeSpec library.
+  - If a spec uses the new type or functionality, existing libraries or emitters may not work with it, and this is not considered a breaking change in the compiler or library that introduced the type. Spec authors should expect that _existing_ specs will continue to work with their workflows, but not that newly-added features will work with their existing workflows every time.
+- TypeScript API types in TypeScript might change in ways that introduce TypeScript type checking errors (e.g. adding a new variant to a union). TypeScript type checking errors in library builds are not considered breaking changes, and library authors working in TypeScript should take care to program defensively as appropriate. More information about TypeScript API guarantees is provided in the section _Categories of Breaking Changes_ below.
+
+### Bugs
+
+A bug fix that requires breaking will not be considered a breaking change if the behavior was already broken to start with.
-A bug fix that requires breaking will not be considered a breaking change if the behavior was already broken to start with.
+A bug fix that introduces a technically breaking change will not be considered a breaking change for the purposes of TypeSpec versioning if it is clear that the existing behavior was broken or unintended in the first place.
-A bug fix that requires breaking will not be considered a breaking change if the behavior was already broken to start with.
+A bug fix that introduces a technically breaking change will not be considered a breaking change for the purposes of TypeSpec versioning if it is clear that the existing behavior was broken or unintended in the first place.
+
+## Categories of Breaking Changes
+
+- <Badge text="Level 0" variant="danger" />: Those Apis shouldn't be broken unless we make a major
+  version and a lot of consideration should given in making any of those. This should be apis that
+  are recommended to be used by library author.
+- <Badge text="Level 1" variant="note" />: Those describe change that are not semantically relevant
+  but still produce noticeable changes in the output. This could be for example a change in the way
+  the output is formatted.
+- <Badge text="Level 2" variant="tip" />: Those are internal apis that could be accessed but
+  touching it would be at the library author risk and breaking change wouldn't even need to be
+  documented
- <Badge text="Level 0" variant="danger" />: Those Apis shouldn't be broken unless we make a major
-  version and a lot of consideration should given in making any of those. This should be apis that
-  are recommended to be used by library author.
- <Badge text="Level 1" variant="note" />: Those describe change that are not semantically relevant
-  but still produce noticeable changes in the output. This could be for example a change in the way
-  the output is formatted.
- <Badge text="Level 2" variant="tip" />: Those are internal apis that could be accessed but
-  touching it would be at the library author risk and breaking change wouldn't even need to be
-  documented
+- <Badge text="Level 0" variant="danger" />: These are stable core APIs and language features that define fundamental semantics and will not be broken without a major version update. We recommend that library authors depend on these APIs.
+- <Badge text="Level 1" variant="note" />: These are APIs and language features that don't describe semantically meaningful information, but provide information that emitters and libraries may choose to use and may introduce changes in emitter output when the features are changed. For example: formatting.
+- <Badge text="Level 2" variant="tip" />: These are internal APIs intended only for use by the TypeSpec compiler and core libraries. Level 2 APIs may be changed without a a major version update or even documentation of the change. Consuming these APIs is _at your own risk_!
- <Badge text="Level 0" variant="danger" />: Those Apis shouldn't be broken unless we make a major
-  version and a lot of consideration should given in making any of those. This should be apis that
-  are recommended to be used by library author.
- <Badge text="Level 1" variant="note" />: Those describe change that are not semantically relevant
-  but still produce noticeable changes in the output. This could be for example a change in the way
-  the output is formatted.
- <Badge text="Level 2" variant="tip" />: Those are internal apis that could be accessed but
-  touching it would be at the library author risk and breaking change wouldn't even need to be
-  documented
+- <Badge text="Level 0" variant="danger" />: These are stable core APIs and language features that define fundamental semantics and will not be broken without a major version update. We recommend that library authors depend on these APIs.
+- <Badge text="Level 1" variant="note" />: These are APIs and language features that don't describe semantically meaningful information, but provide information that emitters and libraries may choose to use and may introduce changes in emitter output when the features are changed. For example: formatting.
+- <Badge text="Level 2" variant="tip" />: These are internal APIs intended only for use by the TypeSpec compiler and core libraries. Level 2 APIs may be changed without a a major version update or even documentation of the change. Consuming these APIs is _at your own risk_!
+
+| Example                          | Level                               | Description                                                                                                                                                                                                                                                                                       |
+| -------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TypeKit                          | <Badge text="0" variant="danger" /> | TypeKits are the recommend way to expose apis for a library. Those should be extremely stable.                                                                                                                                                                                  |
-| TypeKit                          | <Badge text="0" variant="danger" /> | TypeKits are the recommend way to expose apis for a library. Those should be extremely stable.                                                                                                                                                                                  |
+| TypeKits                         | <Badge text="0" variant="danger" /> | TypeKits are the recommend way to expose APIs from a library. TypeKits that are only available through experimental subpaths may be broken without a major version update, but TypeKits that are available by default may be considered highly stable.                                                                                                                                                                            |
-| TypeKit                          | <Badge text="0" variant="danger" /> | TypeKits are the recommend way to expose apis for a library. Those should be extremely stable.                                                                                                                                                                                  |
+| TypeKits                         | <Badge text="0" variant="danger" /> | TypeKits are the recommend way to expose APIs from a library. TypeKits that are only available through experimental subpaths may be broken without a major version update, but TypeKits that are available by default may be considered highly stable.                                                                                                                                                                            |
+| Additional helpers for a library | <Badge text="0" variant="danger" /> | Depending on the helper this could be considered critical or more advanced usage                                                                                                                                                                                                                  |
-| Additional helpers for a library | <Badge text="0" variant="danger" /> | Depending on the helper this could be considered critical or more advanced usage                                                                                                                                                                                                                  |
+| Additional library helper functions | <Badge text="0" variant="danger" /> | Helper and metadata accessor functions exported from the public surface of the compiler or a TypeSpec library are generally considered stable unless otherwise specified or only exported through an experimental subpath.                                                                                                                                                                                                               |
-| Additional helpers for a library | <Badge text="0" variant="danger" /> | Depending on the helper this could be considered critical or more advanced usage                                                                                                                                                                                                                  |
+| Additional library helper functions | <Badge text="0" variant="danger" /> | Helper and metadata accessor functions exported from the public surface of the compiler or a TypeSpec library are generally considered stable unless otherwise specified or only exported through an experimental subpath.                                                                                                                                                                                                               |
+| TypeSpec Syntax Tree              | <Badge text="2" variant="tip" />    | The TypeSpec AST is internal and may change at any time.                                                                                                                                                                                                                          |
-| TypeSpec Syntax Tree              | <Badge text="2" variant="tip" />    | The TypeSpec AST is internal and may change at any time.                                                                                                                                                                                                                          |
+| TypeSpec AST (`Node`)             | <Badge text="2" variant="tip" />    | The TypeSpec abstract syntax tree is considered for internal use only and may change at any time. **Note**: this is not the same thing as the _type graph_ (`Type` and its variants), which is a Level 0, stable feature; this only applies to `Node` and its variants. Libraries depend on the abstract syntax tree _at their own risk_!                                                                                                                                                                                                                           |
-| TypeSpec Syntax Tree              | <Badge text="2" variant="tip" />    | The TypeSpec AST is internal and may change at any time.                                                                                                                                                                                                                          |
+| TypeSpec AST (`Node`)             | <Badge text="2" variant="tip" />    | The TypeSpec abstract syntax tree is considered for internal use only and may change at any time. **Note**: this is not the same thing as the _type graph_ (`Type` and its variants), which is a Level 0, stable feature; this only applies to `Node` and its variants. Libraries depend on the abstract syntax tree _at their own risk_!                                                                                                                                                                                                                           |
+| Checker                          | <Badge text="2" variant="tip" />    | Checker is an internal of the typespec program                                                                                                                                                                                                                                                    |
-| Checker                          | <Badge text="2" variant="tip" />    | Checker is an internal of the typespec program                                                                                                                                                                                                                                                    |
+| Checker                          | <Badge text="2" variant="tip" />    | Direct use of the Program's type checker instance is considered for internal use only and its API may change at any time.                                                                                                                                                                                                                                                   |
-| Checker                          | <Badge text="2" variant="tip" />    | Checker is an internal of the typespec program                                                                                                                                                                                                                                                    |
+| Checker                          | <Badge text="2" variant="tip" />    | Direct use of the Program's type checker instance is considered for internal use only and its API may change at any time.                                                                                                                                                                                                                                                   |
+| Symbols                          | <Badge text="2" variant="tip" />    | Internals                                                                                                                                                                                                                                                                                         |
-| Symbols                          | <Badge text="2" variant="tip" />    | Internals                                                                                                                                                                                                                                                                                         |
+| Symbols                          | <Badge text="2" variant="tip" />    | TypeSpec node symbols (not JavaScript symbols or state keys, rather the internal symbols used to relate TypeSpec types in the parser and type checker) are for internal use only.                                                                                                                                                                                                                                                                                    |
-| Symbols                          | <Badge text="2" variant="tip" />    | Internals                                                                                                                                                                                                                                                                                         |
+| Symbols                          | <Badge text="2" variant="tip" />    | TypeSpec node symbols (not JavaScript symbols or state keys, rather the internal symbols used to relate TypeSpec types in the parser and type checker) are for internal use only.                                                                                                                                                                                                                                                                                    |
+| Formatter                        | <Badge text="1" variant="note" />   | Formatting shouldn't affect the meaning of the language. Changes to the formatting should be taken with consideration as it could create a lot of diff but it shouldn't also be considered a breaking change                                                                                     |
-| Formatter                        | <Badge text="1" variant="note" />   | Formatting shouldn't affect the meaning of the language. Changes to the formatting should be taken with consideration as it could create a lot of diff but it shouldn't also be considered a breaking change                                                                                     |
+| Formatter                        | <Badge text="1" variant="note" />   | Formatting shouldn't affect the meaning of the language. Changes to the formatting should be taken with consideration, as changes in formatting may introduce significant and unexpected differences in formatted output, but changes to the formatter output are not considered breaking changes for the purposes of issuing a major version change.                                                                                     |
-| Formatter                        | <Badge text="1" variant="note" />   | Formatting shouldn't affect the meaning of the language. Changes to the formatting should be taken with consideration as it could create a lot of diff but it shouldn't also be considered a breaking change                                                                                     |
+| Formatter                        | <Badge text="1" variant="note" />   | Formatting shouldn't affect the meaning of the language. Changes to the formatting should be taken with consideration, as changes in formatting may introduce significant and unexpected differences in formatted output, but changes to the formatter output are not considered breaking changes for the purposes of issuing a major version change.                                                                                     |
+| Bug                              | [See bug](#bugs)                    | I think if something is found to be a bug from the documented behavior and fixing it is in someway breaking it shouldn't be considered as such unless it is such a widely used item where it has to become a "feature". Those should however still be documented as breaking in the release notes |
-| Bug                              | [See bug](#bugs)                    | I think if something is found to be a bug from the documented behavior and fixing it is in someway breaking it shouldn't be considered as such unless it is such a widely used item where it has to become a "feature". Those should however still be documented as breaking in the release notes |
+| Bug fixes                             | [See bug](#bugs)                    | Bug fixes will not be considered breaking changes for the purposes of TypeSpec versioning if the existing behavior is _clearly_ broken or unintentional (e.g. if it violates the documented and expected behavior, or if there is no reasonable interpretation of the buggy behavior), even if the change is technically a breaking change. Bug fixes that are technically breaking will be documented as breaking changes in the release notes, but will not introduce a major version revision. However, if a bug's behavior has become so widely used as to be considered a "feature," we will consider the impact of the bugfix and make a reasonable determination to the best of our abilities and depending on the non-breaking mitigation strategies we have at our disposal. We will not break behaviors in stable releases that are known to be widely depended upon, even if we believe they are the result of a bug. |
-| Bug                              | [See bug](#bugs)                    | I think if something is found to be a bug from the documented behavior and fixing it is in someway breaking it shouldn't be considered as such unless it is such a widely used item where it has to become a "feature". Those should however still be documented as breaking in the release notes |
+| Bug fixes                             | [See bug](#bugs)                    | Bug fixes will not be considered breaking changes for the purposes of TypeSpec versioning if the existing behavior is _clearly_ broken or unintentional (e.g. if it violates the documented and expected behavior, or if there is no reasonable interpretation of the buggy behavior), even if the change is technically a breaking change. Bug fixes that are technically breaking will be documented as breaking changes in the release notes, but will not introduce a major version revision. However, if a bug's behavior has become so widely used as to be considered a "feature," we will consider the impact of the bugfix and make a reasonable determination to the best of our abilities and depending on the non-breaking mitigation strategies we have at our disposal. We will not break behaviors in stable releases that are known to be widely depended upon, even if we believe they are the result of a bug. |
+
+### Supported node version
+
+TypeSpec intends to support all [current node.js releases](https://nodejs.org/en/about/previous-releases). We may drop support for a maintenance or unsupported node version within a major version.
-### Supported node version
-
-TypeSpec intends to support all [current node.js releases](https://nodejs.org/en/about/previous-releases). We may drop support for a maintenance or unsupported node version within a major version.
+### Supported Node.js Versions
+
+TypeSpec will support all [current, active, and maintenance LTS Node.js releases](https://nodejs.org/en/about/previous-releases). We aim to support newly released current LTS versions as soon as possible, and we will provide a six month "grace period" after an LTS release leaves maintenance support before we cease testing it. After we drop support for a maintenance LTS version of Node.js, we may begin using syntax and runtime features that outdated Node.js versions may not support in new minor versions of published packages.
+
+TypeSpec does not guarantee support for any alternative JavaScript engines or runtimes.
-### Supported node version
-
-TypeSpec intends to support all [current node.js releases](https://nodejs.org/en/about/previous-releases). We may drop support for a maintenance or unsupported node version within a major version.
+### Supported Node.js Versions
+
+TypeSpec will support all [current, active, and maintenance LTS Node.js releases](https://nodejs.org/en/about/previous-releases). We aim to support newly released current LTS versions as soon as possible, and we will provide a six month "grace period" after an LTS release leaves maintenance support before we cease testing it. After we drop support for a maintenance LTS version of Node.js, we may begin using syntax and runtime features that outdated Node.js versions may not support in new minor versions of published packages.
+
+TypeSpec does not guarantee support for any alternative JavaScript engines or runtimes.