Backwards Compatibility
This page documents what is allowed to change, and not, within the production branch of grammar-web and the accompanying libraries.
Public parts are not allowed to change
This project adheres to semantic versioning. This means that for each major version of the libraries, the following parts are considered stable, meaning that they cannot change or be removed:
- Existence of modules exported from
@tpg/grammar-web,@tpg/grammar-web/typesand@tpg/grammar-web/icons- Once something is exported in the production package, it cannot be removed until a new major version
- The public interfaces of exported modules
- Types, classes, members, constants and utility functions that are not marked with a prefixing underscore are considered public interfaces.
- Web component events, attributes, props, slots and CSS parts are considered public interfaces
Additions are allowed
Although components and interfaces are considered stable, there may be additions to both without a new major version.
Fixing regressions is allowed
If some functionality has been released in one state, but unintentionally regresses in a future minor version, this is allowed to be rectified with a patch version, without the fix being considered a breaking change --- since it amends an unintentional potential breaking change.
Non-public parts of the library are allowed to change
The following ARE NOT considered public, and are allowed to change without a new major version:
- Shadow DOM of exported components
- CSS of exported components
- Anything that is not exported in the import paths mentioned in the first section, as long as it doesn’t result in a perceivable change in external functionality of an exported component.
The different stages of deprecation
In cases of bugs with released components, changes to them should adhere to the above promises as far as possible. This means that changes must as far as possible be additions of new alternate methods that accomplish the intended design goal of a bugged part that needs fixing. This is to not break unintended dependence on bugged behavior in downstream applications.
Such additions will come in the form of new minor versions or patches, that keep existing functionality, but adds a deprecation notice on old functionality that will be removed in next major version. The deprecation notice will point to the new way of doing things.
In the case that an issue cannot be solved without changing existing functionality, it will be queued for release in the next major version. We will not have duplicate components the same way we may duplicate single functions or attributes to preserve old functionality besides new. The component that will change will get a deprecation notice in docs and in-editor tooltip once we have a new implementation ready for testing in the beta package.
Maintenance of old major versions
As a rule, only the latest major version is maintained. Do not expect back-porting of new features or components to older versions. In rare cases, important bug-fixes may be back-ported, but a new major version signals a need to prioritize refactoring your use of deprecated components.