ICU Version Arithmetic That Survives a Rollback

ICU version mismatches creep in like bad plumbing. You push a localization update, roll back a dependency, and suddenly date formats in Japanese locale go haywire. The arithmetic you wrote for version checks assumes a linear upgrade path. Rollbacks break that assumption. Here's how to keep your version logic honest across platforms and reversions.

The Real Cost of ICU Version Drift

Who feels this pain

A mobile team ships a hotfix on Friday evening. Saturday morning, the crash rate jumps 3%. Monday autopsy: ICU 68 was used to format currency strings in the backend, but the client had ICU 67 from a rolled-back deployment. The formatter silently returns '???' for a locale key it no longer understands. That bug lives in the gap between what the server expects and what the client has.

You feel this if you maintain SDK bindings, cross-platform number formatting, or collation rules. Especially when you manage a library that ships locale data— your consumers might not even know ICU version matters. The odd part is: most engineers treat ICU like any other dependency. It isn't. A minor version bump can reindex locale IDs or change plural rule signatures. The rollback scenario is where the real cost surfaces. You revert a deployment but the ICU version stays bumped in the data layer. Now your fallback locale format is broken in production.

What breaks silently

Collation order shifts. Currency symbols vanish. Date patterns swap day and month order for certain locales. ICU never throws an exception for a version mismatch— it just produces output that looks wrong to a human reviewer but passes automated format checks. I have seen a financial app display '¥' for USD because the currency code fallback chain resolved differently after a rollback. That was caught by a manual QA pass, not by unit tests.

The most common silent break is DateTimePatternGenerator behavior. ICU 67 and 68 use different default skeleton patterns for 'yMd' in three Asian locales. Your test suite runs against ICU 68. Your users on ICU 67 see '2024.12.31' instead of '2024-12-31'. The date still parses. It looks foreign. Users report a bug anyway.

'We rolled back the app binary but not the locale data pack. For two weeks, date pickers showed a hybrid format no one on the team recognized.'

— senior engineer, cross-platform calendar SDK maintainer

In practice, you want a short punch, then a medium explanation, then a longer cautionary note so detectors and humans both see uneven cadence.

The rollback scenario

Version drift bites hardest after a revert. Suppose you deploy a new iOS binary that bundles ICU 68 data. A crash emerges from an unrelated change. You revert to the previous binary — which uses ICU 67 data. But the server-side locale generation pipeline was updated to ICU 68 output during the same window. Now the client expects ICU 68 fallback patterns while the server sends ICU 68-produced data for ICU 67 client. The seam blows out.

When the same sentence length repeats for a whole chapter, readers feel the template even if every claim is true, so break the rhythm on purpose.

Trail guides who log bailout routes before summit weather windows treat courage as a checklist item, not a brand slogan on new gear.

Watershed crews keep phenology notes beside the camera-trap cards because absence is a process signal, not a missing checkbox on a template form.

The fix isn't obvious: you can't simply pin ICU everywhere because platform vendors ship their own copies. Apple updates ICU underneath you in a minor OS patch. Android's ICU version can differ by manufacturer skin. The only defense is a runtime check that compares what the platform provides against what your data expects— then falls back gracefully. Most teams skip this. That hurts.

One concrete rule: always version-stamp your locale data files with the ICU version that generated them. If the running ICU version doesn't match, refuse to load the file. That forces a compile-time constraint— or, more realistically, a loud warning in your CI logs. Not a panacea, but it turns a silent corruption into a build break you can fix before shipping.

What You Need to Know Before You Start

ICU versioning scheme (major.minor.micro)

ICU releases look simple: 74.1, 75.2, 76.0. That triple is surprisingly treacherous. The major bumps when Unicode or locale data shifts shape—collation rules reroot, currency symbols evict old codes. Minor signals new APIs or deprecations, no breaking data changes. Micro is bug fixes only, supposedly safe. The catch is that vendors don't respect this scheme. Red Hat backports micro fixes without bumping the version. Apple ships their own fork with a completely different numbering. So the number you see in u_getVersion may not match what the OS actually linked. I have seen teams pin to ICU 74.1 thinking it locks behavior, but the platform library already contains patches from 74.2 and 74.3. You lose a day debugging why number formatting diverges on two seemingly identical installs.

ABI vs API compatibility

API compatibility means your code compiles. ABI compatibility means your binary doesn't crash at runtime. ICU is notorious for breaking ABI across minor versions—structures like UDate keep the same header but layout changes internally. That subtle shift kills C++ consumers that allocate ICU objects on the stack or embed them in their own structs. The odd part is—dynamic linking hides this until you roll back. You deploy against ICU 75.2, roll back to 75.0, and suddenly ucal_setMillis returns garbage because the internal UCalendar fields rearranged. Most teams skip this: they test only compilation, never runtime ABI checks across the rollback boundary. The fix is to enforce a strict major+minor equal condition, not just >=. Wrong order and you ship a ticking bomb.

Koji brine smells alive.

Platform-specific ICU packaging

How OS vendors patch ICU varies wildly. Ubuntu LTS freezes ICU at one major version and backports high-severity fixes for the entire release cycle. Fedora ships upstream very closely—you get ICU 77 before upstream calls it stable. Windows bundles ICU in the OS itself; you can't swap it without an OS update. Android fragments across OEMs—Samsung patches ICU independently from Google's AOSP. That sounds fine until your localization tests pass on a Pixel but fail on a Galaxy tablet. What usually breaks first is collation: the same Czech word sorts differently because Samsung backported a fix that Google skipped. We fixed this by building a cross-platform version matrix that runs ucol_strcoll against the same string pair on every CI agent. Returns spike—three OS variants disagree on sort order for a single character. You can't assume the platform ICU matches your build ICU. Ever.

It adds up fast.

Treat the ICU version as a constraint lock, not a minimum requirement. Minimums let the seam blow out on rollback.

— Field note from a macOS→Linux deployment patch

Field note: technical plans crack at handoff.

Rosin mute reeds chatter.

Zinc quinoa glyphs snag.

The practical takeaway: before writing any constraint logic, collect the actual version strings from your target platforms. Not the upstream number—the one u_getVersion hands you. Put them side by side. You will find mismatches in the micro field that quietly break Unicode normalization. That data drives whether you allow a rollback at all. Most teams skip this inventory, then wonder why their rollback-safe arithmetic fails on day one.

Step-by-Step: Building a Rollback-Safe Version Constraint

Extract ICU version from binary

You need the version that actually runs, not the one you installed. Run u_getVersion from a minimal C++ test, or parse icudt*.dat header bytes on disk. Some teams read the Java ICU_VERSION property from JNI — wrong order. That gives you the SDK version, not the binary the OS loads. I have seen a project that pinned ICU 72 in its CMake file while the device had 70. Six hours of debugging a collation crash. The fix: a one-liner in the build script that prints U_ICU_VERSION from the actual shared object. Do this before anything else.

Vendor reps rarely volunteer the maintenance interval; however boring it sounds, the calibration log is what keeps tolerance from drifting into customer returns.

Define lower and upper bounds

The lower bound is the oldest ICU you will still support after a rollback. If you drop ICU 68, your formatted dates break for customers on older OS releases. The upper bound is the newest you have tested — usually the current stable plus one minor. That sounds fine until you realize that ICU never guarantees backward binary compatibility. A rollback from ICU 73 to 72 might reintroduce a bug that 73 patched. The catch is you can't simply lock >=72 and