-
Notifications
You must be signed in to change notification settings - Fork 211
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
Document package and API versioning policies. #4866
Conversation
TypeScript's flexible, structural type system and its compiler's ability to reason about types imposes pretty strict constraints on what we can call a "non-breaking" change. Union types are a prime example given tsc's default rules about unreachable code (which can only be disabled globally). Plenty more examples here. |
@calebmshafer I can't find much info about how VS Code handles breaking changes in its extension API. The API doesn't appear to be versioned. They "give our best effort to avoid breaking API changes" and "never want to break existing extensions". They call their beta APIs "proposed APIs" available only in Insider builds and allegedly not permitted to be used in published extensions. These APIs may have breaking changes in new releases. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good to me now.
/** Sample description of a beta API item. | ||
* @beta Comment describing reason API item is beta that will be included in the public SDK documentation. | ||
* @public | ||
* @deprecated Comment describing reason API item is deprecated and what should be used instead. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In the "API Categories" it is stated that "deprecated tag is typically accompanied by information about the package version in which it became deprecated" - this should be noted here as well I suppose.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
True. It's currently an aspirational lie though - nobody has ever actually included version information in a @deprecated
tag. @aruniverse suggested we start doing that. Perhaps we need to write a script that will add "3.x" to anything currently tagged as deprecated.
Fixes https://github.com/iTwin/itwinjs-backlog/issues/391.
Incidentally fix bug in README: you can't successfully
rush cover
without firstrush build:ci
-ing.TODO