Locara

28 — Release Process

How Locara’s own framework, runtime, CLI, and reference apps are versioned and released. Distinct from how third-party apps are published (that’s 12-registry.md).

Versioning

What gets versioned

  • @locara/sdk — TypeScript SDK consumed by apps.
  • @locara/components — UI component registry.
  • @locara/manifest — manifest schema + validators.
  • @locara/test — test helpers.
  • locara-cli — CLI binary.
  • (Removed: locara-shell. Each Locara app is its own Tauri app; framework crates are linked in.)
  • locara-core, locara-runtime, locara-storage, locara-models, locara-tools — Rust crates.
  • (Removed: a separate Locara client app. The website (locara.app) handles browsing; each app handles its own installation. The optional Locara Manager utility (phase 3+) is versioned separately if/when shipped.)
  • Manifest schema — locara/v1, locara/v2, etc.

Versioning scheme

  • Semantic versioning (MAJOR.MINOR.PATCH).
  • The CLI, SDK, and runtime crates share a major version (they’re co-released).
  • Minor and patch can drift between components but converge on each major.
  • Manifest schema version is independent: locara/v1 may be supported across many MAJOR releases.
  • Reference apps version independently of the framework (they pin a framework version in their lockfile).

Examples:

  • @locara/sdk@0.1.4 — alpha-stage SDK.
  • @locara/sdk@1.0.0 — first stable SDK; manifest locara/v1 is the supported schema.
  • @locara/sdk@2.0.0 — second-major; supports locara/v1 + locara/v2.

What constitutes a breaking change

For framework-level changes:

  • MAJOR (1.x → 2.0):
    • Removing or renaming a public SDK API.
    • Removing a manifest field.
    • Changing default behavior in a way that breaks existing apps.
    • Any change requiring app authors to modify their code.
  • MINOR (1.0 → 1.1):
    • Adding new SDK APIs.
    • Adding new manifest fields (with sensible defaults).
    • New modalities, tools, components.
    • Performance improvements.
  • PATCH (1.0.0 → 1.0.1):
    • Bug fixes.
    • Documentation.
    • Internal refactors with no observable behavior change.

For the manifest schema specifically:

  • Adding optional fields → patch.
  • Adding required fields → major (forces a v2 schema).
  • Removing fields → major.

Release cadence

TypeCadenceScope
PatchWeekly during active development; less often when stableBug fixes, doc updates
MinorRoughly monthlyNew features, additive changes
MajorAt most every 12 months; ideally less frequentBreaking changes, large redesigns

Stable contracts > novel abstractions. We resist the urge to do major releases just to clean up things; cleanups happen via patches and minors.

Release branches

  • main — always-deployable; cuts patches off this branch.
  • release/v1.x — long-lived branch for the v1 line; receives patches + select minor backports.
  • Future: release/v2.x once 2.0 ships.

Releases are tagged on these branches. Tags are immutable.

Release checklist (per release)

For every release, the release captain (project lead in early phases) walks through:

Pre-release

  • All planned PRs merged.
  • CHANGELOG.md updated for the release.
  • Tests pass on main (full CI).
  • Performance benchmarks run; no regressions vs prior release.
  • Manifest schema validators updated (if any field changes).
  • Migration guide published (if any breaking change).
  • Release notes drafted.

Release

  • Version bumped in all relevant package.json / Cargo.toml.
  • Tag created: v1.2.3.
  • CI builds release artifacts (binaries, npm packages, etc.).
  • Reference apps + (if shipped) Locara Manager utility signed + notarized.
  • npm publish for @locara/* packages.
  • crates.io publish for Rust crates.
  • GitHub release created with notes + artifacts attached.
  • Reference apps’ update channels point at new versions.

Post-release

  • Release announcement published (blog post + X/Mastodon/etc.).
  • Documentation site rebuilt with new version.
  • Sample apps in apps/ updated to new SDK version.
  • Monitoring: watch for unusual error patterns via user-reported issues (no telemetry; user must explicitly file).
  • CHANGELOG.md updated for next development cycle.

Channels

Stable

The default release channel. What npm install @locara/sdk gives you. What reference apps build against.

Beta

Pre-release builds, opt-in for testers. Available as:

  • npm: @locara/sdk@beta tag.
  • Reference apps and optional Locara Manager utility: settings option to enable beta channel.

Beta releases:

  • Feature-complete for the upcoming minor or major.
  • Get 1–4 weeks of testing before stable promotion.
  • Bugs filed against beta are highest priority.

Nightly (development)

Bleeding-edge, no stability promises:

  • Built from main daily via CI.
  • Available as @locara/sdk@nightly for adventurous developers.
  • Used internally for dogfooding.

Auto-update behavior

Locara framework (the runtime + CLI)

The framework versions are upgraded per-app, per-publish. When a developer publishes an app, that app is built against the current SDK version (pinned in locara.lock.json).

The Locara runtime can host apps built against multiple SDK major versions in parallel. So an app on @locara/sdk@1.4.0 and another on @locara/sdk@2.0.0 can both run on the same user’s Mac.

Old SDK majors are supported for at least 2 years after the next major’s release. After that, deprecated; apps still load with a warning; eventually drop support entirely (with explicit migration path for publishers).

Reference apps and the optional Locara Manager utility

Each Locara app auto-updates by default (Tauri’s updater plugin). The optional Locara Manager utility, if shipped, also auto-updates. Channels:

  • Stable: users on default settings.
  • Beta: opt-in via settings.

Updates are signed; the same trust mechanics as published apps apply.

Manifest schema

Each Locara app supports the current major of the manifest schema and all prior majors (because the framework is linked into the app). Supporting old schemas indefinitely is the SQLite-style longevity commitment — apps written today will run in 2036.

When a publisher updates an app, they can opt to migrate to a newer schema (e.g., locara/v1 → locara/v2) with appropriate manifest changes. The runtime supports both.

Communication

Changelogs

CHANGELOG.md per package, following Keep a Changelog format:

## [1.2.0] - 2026-04-30

### Added
- New `voice-to-voice` modality.
- `<TranscriptStream>` component.

### Changed
- `llm.chat` now streams by default.

### Fixed
- Memory leak in long-running chat.

### Deprecated
- `llm.chatLegacy()` — use `llm.chat()` instead.

Changelogs are merged into release notes for the announcement.

Release announcements

Blog post on <domain>/blog per minor/major release. Format:

  • What’s new (1–3 highlights with screenshots/code).
  • What’s changed (breaking changes, migration notes).
  • Acknowledgments (contributors).
  • Links to docs, examples.

Patch releases get a CHANGELOG entry; usually no blog post unless notable.

Migration guides

For breaking changes, a /docs/migrations/v1-to-v2.md (or similar) is written before the major release ships. It includes:

  • Concrete code-change examples.
  • Automated codemod where possible.
  • Timeline (when v1 is deprecated, when removed).
  • Compatibility table.

Yanking / unpublishing

npm packages

Yanking a published @locara/* version is avoided because of left-pad-style breakage. If a critical issue ships:

  • Publish a patch with the fix immediately.
  • Update the previous version’s docs to recommend upgrade.
  • Only deprecate via npm’s deprecate command (which shows a warning but doesn’t break installs).

Genuinely toxic releases (security holes, accidental secret leak in package): yank with an explicit advisory.

Apps in the registry

Different mechanism — apps use the kill-switch + revocation in 14-trust-safety.md, not “unpublish.” Apps stay queryable for forensics; runtime refuses to install/run them.

Long-term support (LTS)

The current major version receives:

  • Security patches indefinitely (until truly EOL).
  • Bug fixes for ~2 years.
  • New minor versions for ~12 months.

When a new major ships, the previous major moves to “maintenance” — security and critical bug fixes only.

The manifest schema for a major version is supported by every Locara app shipped after that major forever. An app published in 2026 still loads in 2036 — that’s the long-term commitment.

Pre-1.0 conventions

While we’re in 0.x:

  • API surface may change between minor versions.
  • We use 0.x.y to signal “alpha; expect changes.”
  • Once we ship 1.0.0, the stable contracts kick in fully.

The 1.0.0 milestone is at the end of phase 3 (registry public + 5–10 external publishers + 10+ apps in catalog). Until then, we’re explicitly pre-stable.

Release captain rotation

Once we have multiple maintainers:

  • One maintainer is the “release captain” for each release cycle.
  • Rotates to spread the workload.
  • The captain owns the checklist + the announcement.

Until then, the project lead is the captain by default.

Open questions

  • (open) Should we publish nightly builds of the optional Locara Manager utility (when shipped), or just CLI/SDK + reference apps? Probably just CLI/SDK; nightly builds of the manager are too risky.
  • (open) Tagging strategy — v1.2.3 vs sdk@v1.2.3? Mono-versioning is simpler; per-package versioning is more flexible. Lean mono-versioning for v1, monorepo-wide tags.
  • (open) Frequency of major releases — could we go many years without one? SQLite has. Probably aim for “never if we don’t have to.”

Cross-references