-
Notifications
You must be signed in to change notification settings - Fork 39
Support policy
iTwinUI employs support policies to facilitate the following objectives:
- Provide a broad set of stable, well-supported UI components.
- Continuously deliver new features, bug fixes, and security updates.
- Evolve APIs over time in response to user feedback.
- Encourage users to keep up to date with the most recent package versions.
Sometimes, APIs evolve in a way that requires making backwards-incompatible changes to them, or removing them altogether. The support policies below detail under what circumstances such breaking changes can occur and how iTwinUI endeavors to minimize their impact on consumers of the library.
- Breaking change
- Any modification that removes or alters functionality in a way that could cause existing software to break.
- Major release
- A version update that may include breaking changes, following semantic versioning.
- Deprecation
- The process of marking a feature or API as obsolete, signaling that it will be removed in future releases.
We aim to minimize breaking changes by designing our APIs for future flexibility. However, evolving needs sometimes necessitate such changes. Here's how we handle them in different iTwinUI packages:
- iTwinUI-Variables breaking changes
- Changes to variable names or significant alterations in values.
- iTwinUI-CSS breaking changes
- Adjustments to the DOM structure, class names, or significant visual updates. The CSS package may adopt a new major version of the Variables package without requiring a new major version of the CSS package.
- iTwinUI-React breaking changes
- Modifications that cause compilation errors or undesirable runtime behavior in existing code. The React package may adopt a new major version of the CSS package without requiring a new major version of the React package.
We adhere to semantic versioning, signaling API changes through our version numbers:
- Patch release
- Patch releases address bugs or security issues without affecting the API.
- Minor release
- Minor releases introduce new features but maintain compatibility.
- Major release
- Major releases are made for significant changes, possibly including breaking changes as outlined in our deprecation policy.
Rare exceptions may be made to this policy when a breaking API change is required to fix a bug and the severity of the bug significantly outweighs the impact of the API change on existing code.
Most public APIs are intended to remain stable indefinitely, but occasionally a breaking change is required to fix a bug, introduce new functionality, or address performance problems. The deprecation policy ensures that such changes are introduced deliberately and predictably to help users plan ahead.
Before a "public" API can be removed it must first be marked as "deprecated" in version N of the package. It must remain stable for the duration of version N+1. Finally, in version N+2 it may be removed. This means that, for example, an API deprecated in version 4.1 of a package cannot be removed until version 6.0 at the earliest.
Each major release of an iTwinUI package undergoes a support lifecycle consisting of the following consecutive phases:
- 🌟 Current
- The most recent major release. It receives regular updates containing new features, bug fixes, and security patches.
- ✅ Active
- Immediately after a new major release, the "current" version becomes an "active" version. It receives updates containing bug fixes and security patches.
- 💀 End-of-life
- After six months an "active" version transitions to "end of life", after which it receives no further updates.
| Major version | Status | Release | Active | End-of-life |
|---|---|---|---|---|
| 1.x | 💀 End of life | 2022-11-14 | 2023-02-27 | 2023-08-27 |
| 2.x | ✅ Active | 2023-02-27 | 2023-10-23 | 2024-04-23 |
| 3.x | 🌟 Current | 2023-10-23 | TBD | TBD |
| Major version | Status | Release | Active | End-of-life |
|---|---|---|---|---|
| 1.x | ✅ Active | 2022-11-14 | 2023-10-23 | 2024-04-23 |
| 2.x | 🌟 Current | 2023-10-23 | TBD | TBD |
| Major version | Status | Release | Active | End-of-life |
|---|---|---|---|---|
| 1.x | 💀 End of life | 2021-04-15 | 2023-01-09 | 2023-07-09 |
| 2.x | ✅ Active | 2023-01-09 | 2023-10-23 | 2024-04-23 |
| 3.x | 🌟 Current | 2023-10-23 | TBD | TBD |