Skip to content
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.

Sign up for GitHub

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

Add breaking change policy to website #6049

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

Add breaking change policy to website #6049

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
66b21fc
Add breaking change policy to website
timotheeguerin Feb 18, 2025
4ed2829
Apply suggestions from code review
timotheeguerin Feb 28, 2025
a7143d6
Merge branch 'main' into breaking-change-policy
timotheeguerin Feb 28, 2025
2b1cda7
Apply suggestions from code review
timotheeguerin Feb 28, 2025
5776fd4
Update website/src/content/docs/docs/handbook/breaking-change-policy.mdx
timotheeguerin Feb 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Apply suggestions from code review 
Co-authored-by: Brian Terlson <brian.terlson@microsoft.com>
  • Loading branch information
@timotheeguerin @bterlson
timotheeguerin and bterlson authored Feb 28, 2025
commit 2b1cda706916e0eae70b34d6efcc080c3f948ca7
8 changes: 4 additions & 4 deletions website/src/content/docs/docs/handbook/breaking-change-policy.mdx
View file
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add the stdout of the compiler is not a contract, use teh api for programmatic usage

Original file line number Diff line number Diff line change
@@ -43,14 +43,14 @@ A bug fix that requires breaking will not be considered a breaking change if the

| Example | Level | Description |
| -------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TypeKit | <Badge text="0" variant="danger" /> | TypeKit will be moving forward 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. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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 SyntaxTree | <Badge text="2" variant="tip" /> | The TypeSpec Ast is not part of the contract a library should depend on. |
| TypeSpec Syntax Tree | <Badge text="2" variant="tip" /> | The TypeSpec AST is internal and may change at any time. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested 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 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 support all currently supported node version by the node foundation.
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
Oops, something went wrong.