Overview
Stability ensures that reusable components and libraries, tutorials, tools, and learned practices don't become obsolete unexpectedly. Stability is essential for the ecosystem around Abyss to thrive.
This document contains the practices that are followed to provide you with a leading-edge UI library, balanced with stability, ensuring that future changes are always introduced in a predictable way.
Semantic versioning
Abyss follows Semantic Versioning 2.0.0. Abyss version numbers have three parts: major.minor.patch. The version number is incremented based on the level of change included in the release.
- Major releases contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs.
- Minor releases contain important new features. Minor releases should be fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release.
- Patch releases are low risk, contain bug fixes and small new features. No developer assistance is expected during update.
Abyss component APIs follow semver strictly. React Native is a peer dependency — upgrading it may require separate changes to your app outside of Abyss. Learn more about supported React Native versions.
Release frequency
A regular schedule of releases helps you plan and coordinate your updates with the continuing evolution of Abyss. In general, you can expect the following release cycle:
- A major release typically every year for major changes.
- A minor release every two weeks after each sprint.
- A patch release at any time for urgent bugfixes.
Deprecation Practices
Sometimes "breaking changes," such as the removal of support for select APIs and features, are necessary.
To make these transitions as easy as possible:
- The number of breaking changes is minimized, and migration tools provided when possible.
- The deprecation policy described below is followed, so that you have time to update your apps to the latest APIs and best practices.
Deprecation Policy
- Deprecated features are announced in the changelog, and when possible, with warnings at runtime.
- When a deprecation is announced, recommended update path is provided.
- Existing use of a stable API during the deprecation period is supported, so your code will keep working during that period.
- Peer dependency updates (React) that require changes to your apps are only made in a major release.
Supported React Native versions
@uhg-abyss/mobile follows a rolling support window, officially supporting the latest 5 React Native minor versions at any given time.
See ADR-025 for the full versioning strategy and rationale.
Why are older versions of React Native dropped?
Supporting every React Native version indefinitely grows the testing surface, increases maintenance overhead, and prevents the team from adopting newer APIs and architecture improvements. Dropping older versions on a predictable schedule keeps the library sustainable while giving teams a reasonable window to upgrade.
Initial adoption
To give teams ample time to upgrade, the new minimum of 0.82.0 will be enforced starting approximately September 1, 2026.
Support window
Abyss tests against the newest supported React Native version.
| React Native | Status | Architecture |
|---|---|---|
| 0.85.x | ✅ Supported | New |
| 0.84.x | ✅ Supported | New |
| 0.83.x | ✅ Supported | New |
| 0.82.x | ✅ Supported | New |
| 0.81.x | ✅ Supported | New / Old |
| < 0.81.0 | ❌ Unsupported | — |
Old architecture was removed by default in React Native 0.82. Abyss tests exclusively on the new architecture.
Peer dependency compatibility
| Dependency | Minimum version |
|---|---|
react-native | >=0.81.0 <1 |
react-native-svg | >=13.0.0 |
react-native-video | >=6.0.0 |
react-native-safe-area-context | >=3.0.0 |
react-native-screens | >=2.0.0 |
@react-navigation/native | >=6.0.0 |
@react-navigation/native-stack | >=6.0.0 |
@react-navigation/bottom-tabs | >=6.0.0 |