Version policy

actor-ts is pre-1.0. The API surface is stable enough to build with, but expect breaking changes at minor-version bumps until 1.0 ships.

This page is the honest assessment of what’s stable, what’s experimental, and what to expect.

Status overview

Area	Status
Core actor model (Actor, ActorRef, ActorOptions)	Stable. API unlikely to change.
Supervision	Stable.
Mailboxes, dispatchers, scheduling	Stable.
Cluster (membership, gossip)	Stable.
Cluster Sharding	Stable; some advanced features (rebalance modes) may evolve.
Cluster Singleton	Stable.
DistributedPubSub	Stable.
DistributedData	Stable.
PersistentActor	Stable.
Snapshot stores	Stable.
Migration adapters	Stable.
HTTP module	Stable for the route DSL; backends may evolve.
Broker actors	Stable. New protocols may add.
Coordination (Lease)	Stable for Lease interface; lease backends may evolve.
Replicated event sourcing	Experimental. API may change.
Worker mesh	Experimental. Use cautiously.
ProducerController / ConsumerController	Experimental. Production use possible; expect refinement.

Versioning until 1.0

Pre-1.0:

• Patch versions (0.x.Y) — bug fixes, no breaking changes.
• Minor versions (0.X.0) — new features, may include breaking changes.
• Major version (1.0.0) — API stabilization commitment.

Read the CHANGELOG before upgrading minor versions.

After 1.0

Once 1.0 ships, strict SemVer applies:

• Patch (X.Y.Z+1) — bug fixes only.
• Minor (X.Y+1.0) — additions; backward-compatible.
• Major (X+1.0.0) — breaking changes; explicit migration guide.

The framework follows a typical conservative SemVer cadence — major version bumps are rare; minor versions add features without breaking existing code.

What “stable” means here

Stable = we don’t expect to break this API. But pre-1.0:

• Method signatures may gain optional parameters.
• Config keys may gain new sub-keys.
• New return-type fields may appear (additive).

Not stable:

• Renaming methods or classes.
• Removing functionality.

If a breaking change happens at a “stable” surface, the CHANGELOG will flag it prominently with a migration note.

What “experimental” means

Experimental = we’re still iterating on the API or implementation:

• Method signatures may change.
• Behavior may change in non-obvious ways.
• Performance characteristics are not yet optimized.

Using experimental features in production is OK — we use them ourselves — but expect to update code at minor-version bumps.

If a feature is deeply experimental (we’re not sure it’ll survive), the docs say so explicitly on that feature’s page.

Deprecation policy

Pre-1.0, there is no guaranteed deprecation cycle. When something is renamed, replaced, or removed, it can be a hard cut at a minor version — the old API is gone in the same release that adds the new one. What you get instead is honesty: the CHANGELOG flags every breaking change prominently (a BREAKING marker + a one-line migration note), so reading it before a minor upgrade tells you exactly what moved. Examples and docs are updated to the new API in the same change.

Post-1.0, this tightens to a proper deprecation cycle: renamed or replaced APIs keep working for at least a full major version with a deprecation warning before removal.

Specific roadmap items

Things we plan to add / change:

• OTel auto-instrumentation polish — better default spans
  • attributes.
• More cluster transports — WebSocket option for browser-bridge, QUIC for edge.
• Sharding rebalance v2 — smarter strategies than least-shard.
• More CRDT types — counter-set, sequence CRDT for ordered lists.

None of these break existing code; they’re additive.

Reporting issues

For bugs or feedback:

• GitHub Issues — for bugs, feature requests, design questions.
• Pull Requests — not accepted. The issue tracker is the contribution channel; open a well-shaped issue and align on the approach there.

Tag issues with the relevant area (cluster, persistence, etc.) so they reach the right code-owners faster.

Where to next

• Configuration — HOCON keys.
• FAQ — common questions.
• Glossary — term reference.
• CHANGELOG — per-version changes.