-
Notifications
You must be signed in to change notification settings - Fork 292
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
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
66b21fc
Add breaking change policy to website
timotheeguerin 4ed2829
Apply suggestions from code review
timotheeguerin a7143d6
Merge branch 'main' into breaking-change-policy
timotheeguerin 2b1cda7
Apply suggestions from code review
timotheeguerin 5776fd4
Update website/src/content/docs/docs/handbook/breaking-change-policy.mdx
timotheeguerin 701d079
Merge branch 'main' of https://github.com/Microsoft/typespec into bre…
timotheeguerin c00c711
apply cr comments
timotheeguerin b9d2055
clarifications
timotheeguerin c6ce6dc
tweaks
timotheeguerin de0dfed
format
timotheeguerin 765ae28
.
timotheeguerin 7ea5bfa
add note on emitter outpuit
timotheeguerin 8fa0a21
format
timotheeguerin File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
56 changes: 56 additions & 0 deletions
56
website/src/content/docs/docs/handbook/breaking-change-policy.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
::: | ||
|
||
## 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. | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## 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). | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
`` | ||
|
||
- 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. | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- 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. | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### Bugs | ||
|
||
A bug fix that requires breaking will not be considered a breaking change if the behavior was already broken to start with. | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## 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 | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
| 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. | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Additional helpers for a library | <Badge text="0" variant="danger" /> | Depending on the helper this could be considered critical or more advanced usage | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| TypeSpec Syntax Tree | <Badge text="2" variant="tip" /> | The TypeSpec AST is internal and may change at any time. | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Checker | <Badge text="2" variant="tip" /> | Checker is an internal of the typespec program | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Symbols | <Badge text="2" variant="tip" /> | Internals | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 | | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### 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. | ||
timotheeguerin marked this conversation as resolved.
Show resolved
Hide resolved
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.