Versions and Compatibility
These release rules apply from 15 October 2026. App 0.1.302 adds automatic checks before plugin installs and updates; 0.1.303 also discovers the connected HA version. Existing installations and data formats are not migrated.
Which version matters?
| Version | Meaning |
|---|---|
| ATLAS App/runtime | Version of the delivered Docker, App/Add-on or Linux package. |
| HA integration | Version of atlas_frontend; record the HACS commit separately. |
| Framework | Independent version per @atlas/* package; not the App version. |
| Plugin | Independent version with a stable ID; manifest, catalog and package must agree. |
| Data format | Kind and format version of persisted data; a revision counts changes for conflict detection. |
The Card Editor ships with ATLAS. External plugins update independently. Equal version numbers across components do not prove compatibility.
Release rules
Use MAJOR.MINOR.PATCH: PATCH for compatible fixes, MINOR for compatible features, and MAJOR for breaking contracts once a stable 1.x interface exists. Before 1.0, a breaking change requires a new MINOR and migration notes. Future incompatible changes must therefore not be another 0.1.x patch. Existing versions are not renamed.
Alpha versions explicitly identify test builds. Changed published package contents require a new version; documentation-only changes need no runtime bump. Record the source commit and tested combinations in release notes.
What does ATLAS check today?
Repository fields compatibility.atlas, host and homeAssistant describe claimed compatibility. atlas refers to the App/runtime. Since 0.1.302, the server checks catalog, package descriptor and embedded manifest declarations together before replacement. SemVer ranges such as >=0.1.302 <0.2.0 are evaluated. A known mismatch or malformed requirement blocks the candidate and preserves the installed version. Missing metadata means unverified and requires explicit confirmation. Installed plugins are not disabled.
host accepts one name or a list of alternatives. administration-local retains its historic meaning of the common Node installer; docker, linux and homeassistant match the configured deployment target. Confirmation cannot override a known incompatibility. Preview writes no files; installation rechecks on the server. Local package imports are checked too.
Since 0.1.303, Administration discovers the HA version from the configured connection's authenticated /api/config response. Tokens and all other HA configuration stay on the server. HA requirements trigger a fresh request before preview and installation; browser-supplied versions are ignored. Missing credentials, timeouts, redirects, denied access and invalid responses stay unknown and require explicit review. A previous successful value is never reused. Beta, RC and development versions remain prereleases. Unknown metadata fields still require review. The read-only /api/homeassistant/version endpoint returns sanitized version metadata or a fixed failure reason; it changes no settings or projects.
Update discovery compares version text numerically; it is not a complete SemVer resolver. Separately, kernel module dependencies support exact numeric triples, ^ and *, but not general ranges or prereleases. Current caret matching keeps the same MINOR for major zero; ^0.0.3 also accepts 0.0.4. Use exact versions for those modules.
Package and manifest ID/version are checked before replacement; repository updates must also match the catalog version. Declared capabilities are neither automatic permissions nor a sandbox. Matching version constraints do not replace functional testing or trust review of a plugin.
Preserve and recover data
- Before updates, back up HA and ATLAS data, or the standalone installation with data and installation identity. Also export local Admin settings, editor projects and shared plugin metadata. External plugin data and browser-only collections need separate backups.
- Keep runtime address, persistent paths and identity stable. Encrypted settings are not automatically portable to another installation. A source backup does not replace a data backup.
- Update one component at a time; restart HA after integration updates as documented. Then check settings, projects and active plugins.
- Recover matching code and the corresponding data snapshot. An older program must not overwrite an unknown newer data format.
Future migrations require a read-only preview, original backup, validated transformation of a copy, explicit apply, conflict checks and atomic replacement. Unknown or damaged formats must not be replaced with empty data. Retries and failures must preserve data. These are requirements, not a claim that universal migration already exists.
Since ATLAS 0.1.304, replacement retains a checked package recovery snapshot under <ATLAS_PLUGIN_DATA_ROOT>/.recovery, inside the existing persistent mount and excluded from public plugin assets. In Plugin Manager, Import package replaces an existing plugin only after a preview and Back up and apply. Restore lists saved versions. Version direction and capabilities are visible; unknown compatibility requires explicit review, and known incompatibility blocks applying. Stale previews are rejected. Files and the shared plugin entry are updated together, preserving activation and repositories. Restoring also backs up the currently installed version.
This restores plugin code. Credentials, editor projects, browser collections and plugin data formats are not reset or migrated. Full backups and matching data snapshots remain necessary. Limits per plugin: 300 files/20 MB per snapshot, 256 MiB and 200 snapshots total. Backups are never auto-purged; full or unreadable recovery storage blocks replacement. The bundled Card Editor is still updated with ATLAS only. Native UI qualification is documented in the scope below.
Verified scope
The actual HACS integration upgrade 0.1.301 → 0.1.306 and HA restarts pass on Pi 5 and Proxmox with settings, projects and plugins preserved. Isolated rollback and re-update pass too. Config-entry format remains 1.1; unknown format 1.2 is refused without rewriting. The integration is qualified against HA 2026.10.1 and additionally isolated 2026.9.4. Further versions and real conversions between different data formats remain open. New migrations require old/current/unknown-format, failure, conflict and restore tests.
UI package recovery passes first in isolation and then on Pi 5 and Proxmox for Icon Library, File Studio and Terminal. Original files, projects, other plugins and checked settings survive. This is not generic rollback of arbitrary plugin data. Separate full HAOS recovery with trash/history and a changed IP is documented in the File Studio guide.
The technical source-repository version policy provides detailed rules and boundaries.