These guides target v0.27.0. Pin the package while qualifying your application and review the versioned upgrade guide before changing it.
Upgrade procedure
- Record the currently deployed package and native-library versions.
- Preserve a supported backup of identity and application state.
- Build against the target release and resolve changed APIs.
- Test restart, pending work and mixed-version peer behaviour on representative devices.
- Release to a limited cohort and inspect failures before expanding.
A previous binary is not automatically a safe rollback for newer persisted state. Follow the release’s storage compatibility guidance. Source on main can contain unreleased features; do not combine generated bindings from one revision with a native library from another.
Runtime changes to qualify
In v0.26, delivery state survives restart, the pending TTL changes from 30 minutes to 24 hours, and deduplication defaults become 2,000 entries retained for 24 hours. Account for the larger retention window in disk and retry budgets. In v0.27, relay group traffic reaches phones. Test group delivery over the relay after upgrading; compilation alone does not exercise these paths.
Upgrading to 0.21.0
A native rebuild is required, because new source files are compiled in on both platforms. Run
pod install for iOS. A JS-only update will not pick them up.
Downgrading is not a rollback. The first launch on 0.21.0 moves delivery state out of the
credential store into the app container and deletes the old copy. An older build comes up
with an empty outbox, an empty pending queue, and an empty block list, meaning every
previously blocked peer is silently unblocked. Roll forward with a hotfix rather than reverting the binary.
