Last updated: 2026-08-25

The Even Hub SDK follows semantic versioning - MAJOR.MINOR.PATCH - with explicit guarantees about what each bump means for your code.

Semver contract

Bump	Means	What can break
PATCH (0.0.13 → 0.0.14)	Bug fix, internal refactor, or - while the SDK is pre-1.0 - an additive, backward-compatible feature (new optional field, new opt-in behavior). Every feature shipped to date arrived this way; the Changelog lists them.	Nothing for code that doesn't opt in to the new field/behavior. Safe upgrade, but read the release notes - 0.0.x patch bumps can add public surface.
MINOR (0.0.x → 0.1.0)	New methods, new event types, new manifest fields	Old code keeps working. Deprecated methods may emit console warnings. Not used yet - every pre-1.0 release to date has shipped as a 0.0.x patch bump instead.
MAJOR (0.x → 1.0)	Breaking changes to method signatures, event payloads, or edition	Existing code may need migration. Follow the migration guide for that release.

The current SDK is in the 0.x series - the platform is signalling "not yet API-frozen." While it's in 0.0.x, every release - bug fix or new feature alike - bumps the trailing digit; there's no separate MINOR release to watch for. Read the release notes for every 0.0.x release before upgrading production apps.

Deprecation window

When a method or field is deprecated:

1. N (current MINOR) - method continues to work; logs a [DEPRECATED] warning in the dev console.
2. N+1 - method continues to work; warning becomes a stack-traced error in the dev console (but no runtime failure).
3. N+2 - method is removed. Calling it throws.

This gives you two MINOR releases to migrate. For example, if oldFoo() is deprecated in 0.2.0, it works through 0.3.x and is removed in 0.4.0.

PATCH releases never deprecate anything.

min_sdk_version migration

Your app's app.json declares min_sdk_version. Bumping it is a one-way trip: users on older firmware can no longer install or update to that version.

Situation	What to set min_sdk_version to
You use only methods present in your current SDK	Match the SDK you npm install-ed
You added a new SDK method introduced in a later version	Match the version where that method first shipped
You hit a bug fix that's only in the latest PATCH	Bump to that PATCH version
You don't know which method needs which version	Run npm list @evenrealities/even_hub_sdk and use that version - conservative but safe

Don't bump preemptively. Higher min_sdk_version strands users on older firmware.

min_app_version and the open-time gate

min_sdk_version (above) is the firmware/SDK floor you set by hand. min_app_version is the phone-app floor - the oldest Even Realities App your build runs on - and you don't set it: the CLI derives it from your SDK version at pack time. When an SDK release adds a bridge API that only a newer app implements, that release publishes the required app version with itself, and evenhub pack reads it and stamps the floor. See Auto-deriving min_app_version.

	min_sdk_version	min_app_version
Who sets it	You, in app.json	The CLI, derived from your SDK version at pack time
What it gates	Install / update on older firmware	Opening the plugin on an older phone app

What the floor does at runtime

The Even Realities App checks a plugin's min_app_version against its own version when the plugin is opened:

• App at or above the floor - the plugin opens normally.
• App below the floor - the plugin is blocked at open with a prompt to update the Even Realities App. No partial launch, no SDK calls. Opening from the glasses is caught the same way - the phone app is always the host - and the block shows as a short message on the glasses telling the user to update on their phone.

The check is local and runs only at open; there's no version block at download or update. Keeping the floor accurate - which auto-derivation does for you - is what stops a working plugin from being needlessly blocked, or a broken one from slipping onto an app too old to run it.

Reading the changelog

The Changelog groups every release by the feature it delivered, across the SDK, the CLI, and the simulator. Read it before upgrading - it is the fastest way to see whether a bump touches anything your app uses.

Each npm package also carries its own raw list in a Changelog section of its README, in the usual shape:

• Added - new methods, events, manifest fields (safe to ignore if you don't need them)
• Changed - non-breaking changes to existing behavior (read for caveats)
• Deprecated - see deprecation window above
• Removed - methods removed at the end of their N+2 cycle (MAJOR bumps only)
• Fixed - bug fixes (read; some bug fixes alter semantics in subtle ways)

Any edition bump is called out explicitly. An edition change is a platform-contract change - your manifest has to declare the new edition before your app loads under it.

Pinning vs. floating

Recommendations for package.json:

{
  "dependencies": {
    "@evenrealities/even_hub_sdk": "0.0.14"
  }
}

Strategy	When
Exact pin ("0.0.14")	Production apps. Repeatable builds. Explicit upgrade decisions.
Tilde ("~0.0.14")	Internal demos. Picks up later 0.0.x PATCH releases automatically. Don't use for shipped apps.
latest tag	Discovery work only. Never in source-controlled package.json.

The CLI accepts npm install @evenrealities/even_hub_sdk@latest to upgrade explicitly.

Edition changes

edition is the platform contract your app targets - currently "202601". An edition bump is a platform-level breaking change: bridge protocols, event names, or fundamental manifest shape have changed.

When a new edition ships:

1. The release notes call it out explicitly, with a migration guide.
2. Existing apps keep working under their old edition.
3. To opt in, set "edition": "<new>" in app.json and audit your code against the migration guide.
4. There's no auto-migration - opting in is a deliberate, per-app choice.

Edition bumps are rare - think years, not months - and well-telegraphed.

Migration checklist

Walk through each step when bumping the SDK in an existing project:

#	Step	Detail
1	Read the release notes	Cover every version between your current SDK and the target. Pay attention to Deprecated and Removed.
2	Run your test suite	Headless Testing on the simulator.
3	Test critical paths via QR sideload	Local Testing on real hardware.
4	Verify against a beta build	Beta Testing is the only mode that gives production-equivalent behavior. Required for anything heading to release.
5	Grep your codebase for deprecated / removed APIs	If the release notes flagged a method, search the repo and migrate before bumping the dep.
6	Allocate appropriately	A MAJOR or edition bump is a sprint, not a side-quest. Don't bundle it with a feature.

Related

• Changelog - what each SDK, CLI, and simulator release delivered
• Installation - current SDK version pin
• Glossary - edition, min_sdk_version, deprecation definitions
• Submission Flow - state machine, reviewer rubric, fix-forward versioning rules