Skip to content

Add breaking change policy to website #6049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Apr 1, 2025
Merged
1 change: 1 addition & 0 deletions website/src/content/current-sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down
Original file line number Diff line number Diff line change
@@ -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
:::

## 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 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.
- 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.

### Bugs

A bug fix that requires breaking will not be considered a breaking change if the behavior was already broken to start with.

## 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

| 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. |
| Additional helpers for a library | <Badge text="0" variant="danger" /> | Depending on the helper this could be considered critical or more advanced usage |
| TypeSpec Syntax Tree | <Badge text="2" variant="tip" /> | The TypeSpec AST is internal and may change at any time. |
| Checker | <Badge text="2" variant="tip" /> | Checker is an internal of the typespec program |
| Symbols | <Badge text="2" variant="tip" /> | Internals |
| 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 |
| 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 |

### 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.
Loading