Support policy - iTwin/iTwinUI GitHub Wiki
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.
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:
-
@itwin/itwinui-variablesbreaking changes - Changes to variable names or significant alterations in values.
-
@itwin/itwinui-cssbreaking 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.
-
@itwin/itwinui-reactbreaking 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.
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.
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.
- 🔧 Maintenance
- Immediately after a new major release, the "current" version becomes a "maintenance" version. It receives updates containing bug fixes and security patches.
- 💀 End-of-life
- After six months a "maintenance" version transitions to "end of life", after which it receives no further updates.
| Major version | Status | Release | Maintenance | End-of-life |
|---|---|---|---|---|
| 1.x | 💀 End of life | 2022-11-14 | 2023-02-27 | 2023-08-27 |
| 2.x | 💀 End of life | 2023-02-27 | 2023-10-23 | 2024-04-23 |
| 3.x | ✅ Current | 2023-10-23 | TBD | TBD |
| Major version | Status | Release | Maintenance | End-of-life |
|---|---|---|---|---|
| 1.x | 💀 End of life | 2022-11-14 | 2023-10-23 | 2024-04-23 |
| 2.x | ✅ Current | 2023-10-23 | TBD | TBD |
| Major version | Status | Release | Maintenance | End-of-life |
|---|---|---|---|---|
| 1.x | 💀 End of life | 2021-04-15 | 2022-11-15 | 2023-05-15 |
| 2.x | 💀 End of life | 2022-11-15 | 2023-10-23 | 2024-04-23 |
| 3.x | ✅ Current | 2023-10-23 | TBD | TBD |