compatibility-budget
Pure-reference for choosing the compatibility matrix - defines tier-1 (must work; covered per-PR) vs tier-2 (must work; covered nightly) vs tier-3 (should work; covered pre-release) vs unsupported (explicitly out of scope). Includes example budgets per product type (web / desktop / mobile / library), the matrix-size cost / coverage trade-off, and templates for documenting "what we support" externally. Use when a team needs to decide which browser / OS / runtime combinations to commit to.
compatibility-budget
Overview
Without an explicit budget, "compatibility" creeps:
A compatibility budget is a deliberate decision: which configurations the team commits to support, at what tier, with what consequences for unsupported configurations.
When to use
§1 - Tier model
| Tier | Definition | CI cadence |
|---|---|---|
| Tier 1 | Must work; failure blocks releases. | Per-PR smoke. |
| Tier 2 | Must work; failure blocks releases on detection. | Nightly full suite. |
| Tier 3 | Should work; broken-here is a known issue. | Pre-release manual / weekly. |
| Unsupported | Explicitly out of scope; bugs closed as "not supported." | None. |
The tier signals engineering investment, not user importance - a configuration with low traffic but contractual obligation may be Tier 1.
§2 - Example budget per product type
Modern web app
| Configuration | Tier |
|---|---|
| Chrome (current + 1 prior) | 1 |
| Edge (current) | 1 |
| Safari (current + 1 prior) | 1 |
| Firefox (current) | 2 |
| iOS Safari (current + 1 prior) | 1 |
| Chrome on Android (current) | 1 |
| Firefox Android | 3 |
| Samsung Internet | 3 |
| Internet Explorer | unsupported |
| < Chrome 100 | unsupported |
Internal SaaS (controlled audience)
| Configuration | Tier |
|---|---|
| Chrome (latest stable) | 1 |
| Chrome (current - 1 stable) | 1 |
| Edge (latest) | 2 |
| Firefox | 3 |
| Safari | 3 |
| All others | unsupported |
Open-source library
| Configuration | Tier |
|---|---|
| Node 18, 20, 22 on Linux | 1 |
| Node 18, 20, 22 on macOS | 2 |
| Node 18, 20, 22 on Windows | 2 |
| Bun (current) | 3 |
| Deno (current) | 3 |
| Older Node EOL versions | unsupported |
Mobile native app
| Configuration | Tier |
|---|---|
| iOS 17, 16 (current + 1 prior) | 1 |
| iOS 15 | 2 |
| iOS 14 | 3 |
| < iOS 14 | unsupported |
| Android 14, 13 | 1 |
| Android 12 | 2 |
| Android 11 | 3 |
| < Android 11 | unsupported |
§3 - Cost / coverage trade-off
The budget directly affects CI cost:
CI cost = N_tier1 × per_PR_cost + N_tier2 × nightly_cost + N_tier3 × manual_review_costFor a typical web product (5 Tier 1 configs + 2 Tier 2 + 4 Tier 3):
A team's CI budget caps the total; the budget shapes the matrix.
§4 - "What we support" template
Publish externally (docs, marketing, README):
# Browser / OS support
We officially support:
## Tier 1 (per-release tested)
- Chrome (current + 1 prior major version)
- Edge (current)
- Safari (current + 1 prior major version)
- iOS Safari (current + 1 prior major version)
- Chrome on Android (current)
## Tier 2 (nightly tested; bugs fixed within 1 release)
- Firefox (current)
## Tier 3 (best-effort; bugs may take longer to fix)
- Firefox on Android
- Samsung Internet
## Unsupported
- Internet Explorer 11 — last supported v1.4.0 (EOL 2025-12-31).
- Chrome < version 100 — security vulnerabilities; not supported.
- Older mobile OSes — see mobile platform support table.
If you experience an issue on a Tier 3 or unsupported configuration,
please open an issue but understand the priority is lower.The external statement sets user expectations; the internal tiers guide engineering.
§5 - Quarterly review
Browsers / OS / runtime versions evolve; the budget needs review:
| Trigger | Action |
|---|---|
| New major OS / browser release | Add to Tier 1; re-evaluate older. |
| Tier 3 configuration generates >5 issues | Promote to Tier 2 OR retire to unsupported. |
| Tier 1 configuration generates 0 issues / quarter | Consider demoting (controversial - get team consensus). |
| Vendor announces EOL | Move to unsupported on EOL date. |
§6 - User-agent telemetry → budget
If the team has analytics on browser / OS distribution, use it:
| Browser | % of users (last 30d) | Recommended tier |
|---|---|---|
| Chrome 130 | 42% | Tier 1 |
| Chrome 129 | 18% | Tier 1 |
| Safari 18 | 15% | Tier 1 |
| iOS Safari 18 | 10% | Tier 1 |
| Edge 130 | 5% | Tier 1 / 2 |
| Firefox 132 | 4% | Tier 2 |
| Chrome 128 and older | 3% | Tier 3 |
| Other (long tail) | 3% | Tier 3 |
The 80/20 rule: if a configuration has <1% usage, Tier 3 or unsupported. If <0.1%, unsupported.
§7 - Compatibility statement vs accessibility commitment
These are different:
A user with a screen reader on Tier 1 Chrome should have Tier 1 accessibility experience. The two budgets compose.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| No documented budget | Compatibility creeps; surprise costs. | Author per §2 + publish per §4. |
| Tier 1 = "everything we can test" | CI cost explodes. | Tier 1 should be the minimum-viable; promote consciously. |
| Unsupported = "we don't talk about it" | Users assume support exists; complaints surprise. | Explicit unsupported list (§4). |
| Quarterly review missed | Budget stale; supports end-of-life software. | Calendar invite (§5). |
| User-agent telemetry ignored | Tier 1 list doesn't match reality. | Use telemetry (§6). |
| Same budget across product variants | A B2B SaaS doesn't need the same browser support as a consumer site. | Per-product budget (§2 examples). |